# Project Context

> Read existing or explicitly create, refresh, remove, and validate source-grounded project routing documentation for a code repository. Use when the user asks for repository project context, "프로젝트 컨텍스트 세팅", "프로젝트 컨텍스트 문서 갱신", "프로젝트 컨텍스트 제거", or invokes "$project-context". Do not trigger for ordinary implementation, debugging, or review merely because onboarding docs are missing.

- Skill: `aqwsde321/project-context` (Agent Skill, multi-file: 21 files)
- Install (CLI): `npx skillmds@latest add aqwsde321/project-context`
- Raw SKILL.md: https://api.skillmd.com/api/skills/aqwsde321/project-context/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Docs & Writing
- Author: aqwsde321 (https://skillmd.com/u/aqwsde321)
- Updated: 2026-09-21
- Page: https://skillmd.com/skills/aqwsde321/project-context

---


# 프로젝트 컨텍스트

## 역할

한국어 질문을 저장소의 영어 용어·코드 식별자·경로에 연결한다. 홈은 짧은 최초 안내서, 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.md`
- `docs/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은 [용어 라우팅](references/wiki-model.md#용어-라우팅), 실제 입력은 [Lookup read set](references/wiki-model.md#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](references/wiki-model.md)만 읽는다.

`init`·`update`에서는 다음을 순서대로 전부 읽는다.

1. [wiki-model.md](references/wiki-model.md)
2. [authoring.md](references/authoring.md)
3. [update-workflow.md](references/update-workflow.md)
4. [validation.md](references/validation.md)

plan의 `project_profile.id`가 `spring`일 때만 source 조사 전에 [spring.md](references/spring.md)를 전부 읽는다.

`remove`에서는 [update-workflow.md](references/update-workflow.md#제거)만 읽는다.

## 불변 계약

- 탐색 깊이는 `홈 → area index → route` 최대 2단계다.
- route가 없으면 single-page 홈 자체가 `id: home`, `type: guide` route다.
- 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 범위의 pinned `reviewed_commit`에서 확인돼야 한다.
- `source_commit`은 본문이 설명하는 기준점, `reviewed_commit`은 route·inventory를 최신 검토한 기준점이다.
- inventory resolution은 [Coverage resolution](references/wiki-model.md#coverage-resolution) 계약을 따르며 `pending`이 남으면 finalize는 실패한다.
- warning은 보고한다. error 또는 non-zero exit는 완료 실패다.

## 실행

정확한 명령과 복구 절차는 [update-workflow.md](references/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`·`excluded` resolution 수
- 미커밋 source와 local-only warning
- 최종 validation 결과

제거에서는 삭제한 문서·marker, 보존한 예상 밖 파일, worktree warning만 보고한다.

현재 변경 검증은 [validation.md](references/validation.md#변경-검증)에 기록한다.