aqwsde321 프로젝트 컨텍스트
역할
한국어 질문을 저장소의 영어 용어·코드 식별자·경로에 연결한다. 홈은 짧은 최초 안내서, area index는 영역 목록, route는 상세 guide 또는 source 검색법이다. lookup helper의 무결성 검사가 내부적으로 읽은 metadata·inventory·source 본문은 모델 입력이 아니다. 모델의 실제 read set은 lookup JSON의 route type·신뢰 상태를 따른다.
이 스킬은 기존 의미를 연결한다. 새로운 도메인 의미·정체성·경계를 합의하지 않는다. 그런 결정이 필요할 때만 $domain-modeling을 별도로 사용한다.
외부 문서 서비스나 코드 인덱서를 설치·호출하지 않는다. 저장소 지침에 지정된 탐색 도구가 있으면 그 지침을 따른다.
helper 실행 계약은 Python 3.11+와 Git이다. TOML은 stdlib tomllib으로 읽는다.
권한과 안전
사용자가 프로젝트 컨텍스트 생성·세팅·갱신을 명시했거나, 더 좁은 read-only 요청 없이 $project-context를 직접 호출한 경우에만 write한다. 문서 부재·stale 또는 일반 구현·디버깅·리뷰 요청은 write 권한이 아니다.
제거는 사용자가 프로젝트 컨텍스트 제거를 명시한 경우에만 실행한다. remove preview를 먼저 확인하고 remove --write로 확정한다.
허용 write:
docs/project-context.mddocs/project-context/- top-level
AGENTS.md또는CLAUDE.md의 project-context marker - 사용자가 worktree 공유를 명시한 경우 같은 Git common directory의 등록 worktree top-level marker
source code, .gitignore, unmarked 사용자 지침은 수정하지 않는다. secret·credential·private key를 읽거나 문서화하지 않는다. managed path의 symlink, repo 밖 경로, absolute host path, private URL을 거부한다. .env*는 example도 source inventory 전에 제외한다.
조사와 문서 근거는 실행 시작 시 고정한 committed HEAD를 사용한다. 미커밋 source는 수정·근거화하지 않고 별도로 보고한다.
읽기와 라우팅
일반 질문은 lookup --query를 먼저 실행하고 선택·동률·fallback은 용어 라우팅, 실제 입력은 Lookup read set의 canonical 계약을 따른다.
다음 두 문단은 canonical lookup 계약을 target 저장소에 투영하는 agent marker와 동일하게 유지한다.
질문에 저장소 상대 경로나 basename이 명시돼도 pinned HEAD tree에서 유일하게 확인되는 실제 경로일 때만 프로젝트 컨텍스트 홈을 우회해 해당 source를 직접 조사한다. 존재하지 않는 경로, 여러 경로와 일치하는 basename, 주문 취소 경로 같은 자연어는 일반 라우팅을 따른다. 영향 범위가 필요할 때만 source map에서 관련 guide 하나를 추가로 확인한다.
routing 결과는 primary route 하나만 연다. guide_body_trusted가 true인 guide는 그 route로 답하고 필요한 세부가 없을 때만 source_paths의 현재 source를 확인한다. search 또는 신뢰하지 못한 guide는 route의 안내와 source_paths로 현재 source를 조사한다. 후보 동률이면 JSON의 read_when으로 하나를 고르며 모든 route를 열지 않는다. lookup 실패 시 반환된 fallback 하나만 열고 현재 source를 확인한다.
모드
chat: 문서와 metadata를 수정하지 않는다. lookup 결과에 필요한 문서만 읽는다.init: 홈이 없는 저장소에 schema v3 문서를 만든다.update: 기존 schema v3 문서의 영향 route와 inventory resolution을 갱신한다.remove: managed 문서와 project-context marker를 제거한다. 기본 실행은 preview이며--write가 있어야 삭제한다.
v1·v2 migration은 지원하지 않는다. 기존 _plan.md, HISTORY.md, 구 metadata가 있으면 자동 변환하지 말고 사용자의 이전 문서 삭제 의도를 확인한 뒤 v3로 다시 생성한다.
Worktree 공유
문서는 등록 worktree 하나를 canonical로 두고 한 번만 만든다. 사용자가 다른 곳을 지정하지 않으면 현재 worktree를 canonical로 사용한다. 공유 요청이 있을 때만 helper가 같은 Git common directory의 consumer marker에 canonical 홈의 상대 링크를 쓴다.
consumer에서는 project-context write 명령을 실행하지 않는다. 공유 문서의 repo-relative source와 dependency 경로는 consumer root에 다시 붙이며 canonical worktree의 source 파일을 열지 않는다. 자동 탐색한 stale·invalid worktree는 경고만 하고 삭제하거나 git worktree prune하지 않는다.
공유 컨텍스트 제거도 canonical에서만 실행한다. consumer marker가 있으면 remove --write --share-worktrees로 해당 canonical을 가리키는 marker를 함께 제거한다. 다른 canonical이나 local marker는 건드리지 않는다.
참조 문서
chat에서 구조 해석이 필요하면 wiki-model.md만 읽는다.
init·update에서는 다음을 순서대로 전부 읽는다.
- wiki-model.md
- authoring.md
- update-workflow.md
- validation.md
plan의 project_profile.id가 spring일 때만 source 조사 전에 spring.md를 전부 읽는다.
remove에서는 update-workflow.md만 읽는다.
불변 계약
- 탐색 깊이는
홈 → area index → route최대 2단계다. - route가 없으면 single-page 홈 자체가
id: home,type: guideroute다. - multi-page 홈은 route term을 갖지 않고 area만 안내한다.
- area index는
guide와search를 같은 방식으로 나열한다. search-only area도 유효하다. - route frontmatter는 route 항목의 원본이다. 홈·area index의 marker와
.metadata.json.route_index는 area·route frontmatter에서 만든 generated projection이다. - 모든 route는 source/search 시작 경로를 가진다. 첫
user_terms는 자기 route를 유일하게 선택하고, 선언한 모든code_terms는 해당 route 범위의 pinnedreviewed_commit에서 확인돼야 한다. source_commit은 본문이 설명하는 기준점,reviewed_commit은 route·inventory를 최신 검토한 기준점이다.- inventory resolution은 Coverage resolution 계약을 따르며
pending이 남으면 finalize는 실패한다. - warning은 보고한다. error 또는 non-zero exit는 완료 실패다.
실행
정확한 명령과 복구 절차는 update-workflow.md만 따른다. 생성·갱신은 plan read-only → 필요한 문서 작성 → plan --write → resolution 편집 → agent marker 갱신 → finalize → validate, 제거는 remove preview → remove --write다.
완료 보고
- 홈과 생성·갱신한 route
- 생성·갱신한 area index
- agent marker와 worktree 공유 상태
guide·search·excludedresolution 수- 미커밋 source와 local-only warning
- 최종 validation 결과
제거에서는 삭제한 문서·marker, 보존한 예상 밖 파일, worktree warning만 보고한다.
현재 변경 검증은 validation.md에 기록한다.