sergeylopukhov/context-cartographer

Context Cartographer

앞으로 에이전트가 필요한 컨텍스트만 로드할 수 있도록 작은 문서 시스템을 구축합니다.

범위 경계

• 문서 시스템 설정, 감사, 마이그레이션, 정리, 재구성 또는 불명확한 소유권에 이 스킬을 사용합니다.
• 대상 소유자 파일이 이미 알려진 일상적인 편집에는 사용하지 마십시오.
• AGENTS.md, CLAUDE.md, Cursor 규칙, docs/architecture.md 또는 docs/code_rules.md에서 이미 요구하는 자동 영구 유지보수에는 사용하지 마십시오. 해당 로컬 지침을 직접 적용하세요.
• 사용자가 명시적으로 context-cartographer를 호출할 때 항상 사용하십시오.

핵심 규칙

• 프로젝트 파일을 읽기 전에 프로젝트 루트를 확인하고 실제 경로를 목록화하십시오. 현재 디렉터리나 다른 프로젝트에서 경로를 추측하지 마십시오.
• 작업 중 이미 읽은 파일은 재사용하십시오. 변경된 파일, 잘린 출력, 또는 특정 읽지 않은 범위만 다시 읽으십시오.
• 루트 에이전트 명령 파일은 짧게 유지하십시오. 영구적인 주제 세부 정보는 docs/ 아래의 소유자 파일에 두십시오.
• Codex에는 AGENTS.md, Claude Code에는 CLAUDE.md, Cursor에는 .cursor/rules/context-cartographer.mdc 또는 선택된 다중 에이전트 대상을 위한 얇은 어댑터를 사용하십시오.
• 변경을 제안하기 전에 읽기 전용으로 검사하십시오.
• 기존 프로젝트별 규칙을 보존하고 정밀하게 편집하십시오.
• 승인 없이 기존 명령 또는 문서 파일을 덮어쓰거나, 이동하거나, 병합하거나, 삭제하지 마십시오.
• 프로젝트 증거와 현재 필요에 의해 지원되는 파일만 생성하십시오.
• 알 수 없는 사실은 TODO: clarify로 표시하고, 프로젝트 사실을 절대 만들어내지 마십시오.
• 프로젝트 메모리 문서는 기본적으로 로컬 전용으로 유지하고, 사용자가 명시적으로 추적 또는 게시를 요청하지 않는 한 저장소 무시 파일에 추가하십시오.
• 편집 후 링크, 소유자 라우팅, 무시 규칙, 오래된 참조를 확인하십시오.

필수 결정 사항

루트 에이전트 지침을 만들거나 교체하기 전에 다음을 결정하십시오:

• 에이전트 대상;
• 코드 규칙 모드: docs/code_rules.md 사용 또는 사용 안 함;
• 문서 유지보수 모드: 자동 영구 유지보수(automatic durable maintenance) 또는 요청 시 유지보수(request-only maintenance);
• 기존 문서 처리: 그대로 유지, 감사 전용, 승인 후 마이그레이션, 또는 에이전트가 결정하도록 위임;
• 프로젝트 메모리 문서를 로컬 전용으로 유지할지 추적할지 여부.

코드 규칙 모드 또는 문서 유지보수 모드를 추론하지 마십시오. 두 가지 이상의 결정이 누락된 경우 번들 설문지를 사용하십시오.

생성된 루트 지침은 일상적인 유지보수가 이 스킬과 독립적으로 유지되도록 해야 합니다:

• 자동 영구 유지보수 하에서는, 완료된 작업이 영구적인 동작, 아키텍처, 설정, 배포, 스테이징, 테스트 데이터, 액세스, 가져오기/내보내기, 공개 URL, 운영자 워크플로, 데이터 모델, 공개 인터페이스, 에이전트 워크플로 또는 문서 소유권을 변경할 때마다 동일한 작업에서 일치하는 소유자 문서를 업데이트하십시오.
• 요청 시 유지보수 하에서는, 명시적으로 요청된 경우에만 문서를 업데이트하고 오래된 문서에 플래그를 지정하십시오.
• 일상적인 유지보수는 루트 지침과 기존 소유자 문서를 직접 사용하며 context-cartographer를 호출하지 않는다고 명시하십시오.
• 기존 소유자 파일이 적합하지 않은 경우 이 스킬을 호출하고 누락된 소유자 프로토콜을 따르십시오. 자동 영구 유지보수 하에서는, Markdown 파일을 생성할 권한만을 위해 묻지 않고 가장 작은 정당한 소유자를 자동으로 분류하고 생성하십시오.
• 이후에는 설정, 감사, 마이그레이션, 정리, 재구성, 명시적 사용 또는 명확하지 않은 소유권에 대해서만 이 스킬을 호출하십시오.

참조 라우팅

• 처음 설정 시 항상 references/setup-workflow.md를 읽으십시오. 다른 필수 참조를 안내합니다.
• 감사, 마이그레이션, 정리, 재구성 또는 불명확한 소유권의 경우 항상 references/existing-docs-workflow.md를 읽으십시오. 다른 필수 참조를 안내합니다.
• 파일 또는 소유권을 선택하기 전에 references/doc-map.md를 읽으십시오.
• 루트 지침 또는 docs/*.md를 생성하기 전에 references/file-templates.md를 읽으십시오.
• 기존 저장소를 감사하기 전에 references/audit-checklist.md를 읽으십시오.
• 문서를 분할, 병합, 삭제 또는 이름 변경하기 전에 references/cleanup-rules.md를 읽으십시오.
• 설문지 JSON을 생성하기 전에 references/question_schema.md를 읽으십시오.
• 설문지 흐름을 적용할 때만 references/questionnaire_usage_examples.md를 읽으십시오.

워크플로

1. rg --files로 프로젝트 루트와 인벤토리 경로를 확인하십시오.
2. 프로젝트 프로필, 선택된 에이전트 대상, 기존 문서, 소유권, 코드 규칙 모드 및 유지보수 모드를 분류하십시오.
3. 기존 문서의 경우 편집하기 전에 현재 파일, 주제 소유자 및 계획된 생성/업데이트/삭제 작업의 간결한 맵을 표시하십시오.
4. 사용자가 승인한 범위 내에서 가장 작은 정당한 문서 시스템 변경을 적용하십시오.
5. 링크, 오래된 파일 이름, 소유자 적용 범위, 로컬 전용 무시 규칙 및 독립적인 일상 유지보수 지침을 확인하십시오.

새 시스템의 경우 references/setup-workflow.md를 따르십시오.

감사, 정리, 마이그레이션, 재구성 또는 불명확한 소유권의 경우 references/existing-docs-workflow.md를 따르십시오.

설문지

두 가지 이상의 결정이 누락된 광범위한 설정 작업의 경우:

1. references/question_schema.md에서 .project-questionnaire/questions.json을 생성하십시오.
2. language를 사용자 또는 프로젝트 언어로 설정하십시오.
3. python3 <this-skill>/scripts/questionnaire_server.py --input .project-questionnaire/questions.json --validate-only로 유효성을 검사하십시오.
4. 자동 포트로 127.0.0.1에서 서버를 실행하십시오.
5. 사용자가 저장하고 완료했다고 말한 후 계속하기 전에 두 답변 파일을 모두 읽으십시오.

코드 규칙 모드와 문서 유지보수 모드는 기본값이나 권장 옵션 없이 필수 선택 사항이어야 합니다.

업데이트 확인

python3 <this-skill>/scripts/check_update.py --json을 하루에 최대 한 번 실행하십시오. 사용 가능한 업데이트를 설치하기 전에 물어보십시오. 설치된 사용자가 받아야 하는 변경 사항을 게시할 때 VERSION을 업데이트하십시오.

종료 기준

다음을 보고하십시오:

• 생성되거나 변경된 파일;
• 링크, 라우팅 및 오래된 참조 확인;
• 로컬 전용 무시 정책 확인;
• 독립적인 자동 유지보수 라우팅 확인;
• 수행된 유효성 검사 및 실행되지 않은 검사.