프로젝트 컨텍스트 생성기은(는) 무엇을 하나요?
.claude/docs/project.md 파일을 생성하거나 업데이트합니다. 이 파일은 Claude가 매 대화마다 로드하는 간결한 프로젝트 참조 파일입니다. 사람을 위해 작성된 README와 달리, project.md는 Claude를 위해 작성됩니다: 밀도 있고, 사실적이며, 마케팅 문구가 없습니다.
이 스킬이 필요한 이유
.claude/docs/project.md는 CLAUDE.md를 통해 모든 Claude 대화에 자동으로 로드됩니다. 이 파일이 없거나 오래되면 Claude는 기술 스택, 테스트 명령어, 아키텍처를 다시 파악하는 데 많은 시간을 낭비합니다. 이 스킬은 이러한 자동 발견 과정을 자동화하고 간결하고 정확한 참조 파일을 생성합니다.
워크플로우
1단계: 코드베이스 분석
구조화된 3단계 분석을 실행하여 프로젝트 사실을 수집합니다. 모든 사실에 신뢰도 수준을 태그하세요: [confirmed] (소스에서 직접 읽음), [inferred-high] (강력한 증거), [inferred-low] (부분적 증거), [unknown].
자세한 도구 동작, glob/grep 패턴, 레코드 템플릿은 references/analysis-methodology.md를 참조하세요.
1단계 — 프로젝트 메타데이터: 패키지 관리자 파일, 환경 템플릿, CI 설정, 툴체인 파일을 찾기 위해 glob을 사용합니다. 추출할 항목: 프로젝트 이름, 언어, Python 버전, 의존성 (용도 포함), 스크립트/명령어, 환경 변수, CI 단계, 테스트 마커.
2단계 — 아키텍처 스캔: 모든 소스 파일을 검색합니다. 진입점 식별, 임포트 그래프 작성, 모듈 분류 (코어/리프/오케스트레이터), 아키텍처 패턴 식별. 소스 코드에서 참조하는 설정 파일을 읽습니다.
3단계 — 데이터 소스 및 인프라: 외부 데이터 소스 (데이터베이스, API, 파일), 출력 대상 (파일, 업로드, API), 테스트 구조, 사용자 정의 예외 계층 구조를 식별합니다.
2단계: 명확한 질문
분석 후, [inferred-low] 및 [unknown] 항목에 대해 사용자에게 질문합니다. 집중하세요 — 이미 알고 있는 것에 대해 묻지 마세요. 일반적인 공백:
- 프로젝트 목적: 이 프로젝트는 어떤 문제를 해결하나요? (코드에서 명확하지 않은 경우)
- 데이터 소스: 어떤 시스템이 데이터를 제공하나요? 출력은 어디로 가나요?
- 배포: 이 프로젝트는 어떻게/어디서 실행되나요? (로컬, 예약, 클라우드)
코드베이스가 간단하다면 질문이 1-2개 또는 전혀 없을 수도 있습니다.
3단계: project.md 생성
아래 구조를 사용하여 파일을 작성합니다. .claude/docs/project.md가 이미 존재하는 경우, 덮어쓰기 전에 사용자에게 확인하세요.
출력 구조
생성된 project.md는 다음 구조를 따라야 합니다. 프로젝트 규모에 맞게 깊이를 조정하세요 — 작은 프로젝트는 섹션을 생략할 수 있고, 복잡한 프로젝트는 하위 섹션을 추가할 수 있습니다.
# {프로젝트 이름} — 프로젝트 컨텍스트
{한 줄 설명: 무엇인지, 무엇을 하는지, 핵심 기술.}
## 기술 스택
- **{언어/런타임}** — {버전 제약 조건 (알고 있다면)}
- **{프레임워크}** — {용도}
- **{핵심 라이브러리}** — {목적}
- ...글머리 기호 목록, 도구 이름은 굵게, 용도는 주석 처리
## 프로젝트 레이아웃
```text
{주석이 포함된 디렉터리 트리 — 항목당 하나의 짧은 구문}
데이터 흐름
{소스 → 변환 → 출력 파이프라인을 보여주는 ASCII 다이어그램}
데이터 소스
{SOURCE_NAME}— {제공하는 것}- ...데이터베이스, API, 로컬 파일 등
테스트 마커
{테스트 명령어}— {실행하는 것}{마커 이름}— {게이트하는 것}
주요 아키텍처 패턴
- {패턴 이름} (
{파일}): {한 문장 설명} - ...강조할 가치가 있는 비자명한 패턴만
작성 지침
- 밀도 있게, 장황하지 않게. 모든 줄이 자리를 차지해야 합니다. Claude는 동기 부여나 맥락 설정이 필요하지 않습니다 — 사실만 필요합니다.
- 구체적으로, 일반적으로 하지 않게. "
uv run pytest -m 'not snowflake'실행"이 "외부 의존성을 제외한 테스트 실행"보다 낫습니다. - 패턴당 한 문장. 아키텍처 패턴은 각각 한 줄로 — 이름, 파일, 설명.
- 실제 명령어. 테스트 명령어는
pyproject.toml이나 CI 설정에서 복사하고, 의역하지 마세요. - 의존성에 주석을 답니다.
polars만 나열하지 말고polars — 고성능 DataFrame이라고 씁니다. - 데이터 소스는 중요합니다. Claude는 어떤 외부 시스템이 있는지 알아야 합니다. 모든 데이터베이스, API, 파일 소스를 나열하세요.
- 100줄 미만으로 유지하세요.
project.md가 약 100줄을 넘으면 너무 자세한 것입니다 — 세부 사항은 전용 문서로 옮기고 링크를 겁니다.
출력
파일을 .claude/docs/project.md로 저장합니다 (필요하면 디렉터리를 생성합니다). 파일이 이미 존재하는 경우, 덮어쓰기 전에 사용자에게 diff 요약을 보여줍니다.
project.md를 생성한 후, CLAUDE.md가 이를 참조하는지 확인하세요. 참조하지 않는 경우, 다음과 같은 줄을 추가할 것을 제안하세요:
프로젝트 세부 사항 (기술 스택, 아키텍처, 테스트 마커)은 [.claude/docs/project.md](.claude/docs/project.md)를 참조하세요.