프로젝트 컨텍스트
사용자가 프로젝트의 안정적인 규칙을 각각의 적절한 파일에 결정하고 작성하도록 도와줍니다. 사용자가 결정을 내립니다: 읽고, 구체적인 옵션을 제안하며 초안을 작성합니다.
Spec Kit의 constitution.md를 대체합니다. 모든 내용은 더 적합한 위치로 이동합니다:
| 내용 | 파일 | 읽는 대상 |
|---|---|---|
| 스택, 계층, 의존성 규칙, 불변 원칙, 용어집 | docs/ARCHITECTURE.md | 사람과 에이전트; spec-to-plan과 review-spec이 원칙을 확인함 |
| 품질, 브랜치, 커밋, PR, 리뷰, AI 사용 | CONTRIBUTING.md | 사람(및 링크를 통해 에이전트) |
| 각 구조적 결정의 이유와 폐기된 대안 | docs/adr/NNNN-*.md | 필요 시 사람과 에이전트 모두 |
| 명령, 경계, 명확하지 않은 규칙, 문서 맵 | AGENTS.md (+ @AGENTS.md를 포함한 CLAUDE.md) | 모든 세션에서 에이전트 |
| 취약점 보고 방법, 에이전트 정책 | SECURITY.md | 사람 |
템플릿은 assets/en/(영어) 및 assets/es/(스페인어)에 있습니다. 프로젝트가 문서화된 언어를 사용하세요; 명확하지 않으면 물어보세요. 각 템플릿은 시작 주석에 작성 방법을 설명합니다.
규칙
- 중복하지 마세요.
pyproject.toml, CI, 린터에 이미 있는 내용은 링크로 연결하고 복사하지 마세요. 원칙이 두 파일에 나타나면 결국 모순이 생깁니다: 원칙은ARCHITECTURE.md에만 존재합니다. - 짧은
AGENTS.md: 150줄 미만. 포함하지 않고 연결하는 맵입니다. 각 줄에 대해: "이 줄을 제거하면 에이전트가 잘못 이해할까?" 그렇지 않으면 제거합니다. - 도구로 확인할 수 있는 것은 도구로 확인합니다. 각 원칙에 대해 어떻게 검증되는지(린트, import-linter, 테스트, CI, 리뷰) 질문하고 해당 열에 기록합니다.
- 변경 가능한 내용 없음: 스프린트 상태나 TODO는 포함하지 않습니다. 이는 트래커나
docs/plans/에 넣습니다. - 각 파일의 전체 내용(또는 이미 존재하는 경우 차이점)을 보여주고 사용자가 승인한 후에만 작성합니다.
프로세스
1. 프로젝트 읽기
무엇이든 묻기 전에 매니페스트(pyproject.toml, package.json, go.mod…), README.md, 기존 컨텍스트 파일, .github/workflows/, 린터 설정, 폴더 구조를 읽습니다. 찾은 정보를 사용하여 열린 질문 대신 답변을 제안합니다.
모드를 결정하고 사용자에게 알립니다:
- Greenfield(코드가 없거나 거의 없음):
ARCHITECTURE.md는 규범적(prescriptive)이며, 어떻게 될 것인지를 나타냅니다. - Brownfield:
ARCHITECTURE.md는 기술적(descriptive)이며, 현재의 모습을 나타냅니다. 이상적인 상태는 ADR과 도구의 래칫(ratchets)에 기록됩니다. 컨텍스트 파일이 이미 존재하면 차이점에 대해서만 질문하고 diff를 제안합니다. constitution.md에서 마이그레이션: 위 표에 따라 내용을 분배하고 삭제하거나 링크로 축소하도록 제안합니다.
2. 라운드별 인터뷰
한 번에 하나의 카테고리씩 진행합니다. 각 질문에 대해 구체적인 옵션(A, B, "열어둠", "기타")을 제시합니다. 파일이 이미 답변을 제공하는 경우 질문 대신 확인을 요청합니다. 카테고리가 적용되지 않는 경우(예: 데이터베이스가 없는 경우) 건너뛰고 그렇게 말합니다. 각 라운드가 끝나면 결정된 사항을 요약합니다.
| 라운드 | 결정 사항 | 대상 파일 |
|---|---|---|
| 1. 목적 | 프로젝트가 무엇이고 범위를 벗어난 것; 유형(앱, 서비스, 라이브러리, CLI) | ARCHITECTURE.md §1, README.md |
| 2. 스택 및 아키텍처 | 언어, 프레임워크, 영속성, 인프라; 계층 또는 모듈 및 무엇이 무엇을 import할 수 있는지 | ARCHITECTURE.md §2–4, 구조적 결정당 하나의 ADR |
| 3. 불변 원칙 | 5–10개의 안정적이고 검증 가능한 규칙: 이유와 각각이 어떻게 확인되는지 | ARCHITECTURE.md §5 |
| 4. 품질 | 테스트 우선 또는 사후, 최소 커버리지, 타입 지정, 절대 모킹하지 않는 것 | CONTRIBUTING.md §5; 불변 원칙이면 원칙에도 포함 |
| 5. 보안 | 인증, 민감 데이터, 입력 검증, 규제 준수 | ARCHITECTURE.md §10, SECURITY.md |
| 6. 프로세스 | 브랜치, Conventional Commits, 병합 또는 스쿼시, 승인, PR 크기, 허용되는 AI 도구 | CONTRIBUTING.md §4, §6–7 |
| 7. 의존성 | 추가 정책, 금지된 라이브러리, 빌드 또는 구매 | 원칙(불변 원칙인 경우) 또는 CONTRIBUTING.md |
| 8. 에이전트용 | 명령(검증 명령은 필수), 명확하지 않은 규칙, 중요하거나 취약한 영역(Brownfield), 경계(항상/물어보기/절대) | AGENTS.md |
라운드 8에서 검증 명령은 다른 스킬(plan-to-tasks, implement, 리뷰)과의 계약입니다. 존재하지 않으면 setup-guardrails-python(또는 해당 언어에 해당하는 것)을 제안하거나 AGENTS.md에 열린 질문으로 남겨둡니다. 프로젝트가 review-prepush 또는 review-pr을 사용할 경우, 선택적 ## Code review 섹션(review-context/assets/AGENTS-code-review.md 템플릿: 기본 브랜치, 고위험 경로, 보고 언어…)도 제공합니다.
3. 초안 작성 및 기입
순서: ARCHITECTURE.md → ADR → CONTRIBUTING.md → SECURITY.md → AGENTS.md. AGENTS.md는 모든 파일을 연결하므로 마지막에 옵니다.
assets/의 템플릿에서 시작합니다. 아직 적용되지 않는 섹션은 빈 상태로 두지 말고 삭제합니다.- ADR:
ADR.md를docs/adr/0000-template.md(스페인어:0000-plantilla.md)로,adr-README.md를docs/adr/README.md로 복사합니다. 라운드 2-3의 각 구조적 결정에 대해 하나의 ADR을 생성합니다. Brownfield: 가장 많이 질문받은 내용에 대해 폐기된 대안과 함께 3-5개의 소급 ADR만 생성합니다. AGENTS.md에는 다음이 포함되어야 합니다:- "Planning" 줄: 구현 전에
docs/ARCHITECTURE.md의 원칙에 대해 계획을 확인합니다; - 프로세스를 위한
CONTRIBUTING.md링크.
- "Planning" 줄: 구현 전에
CLAUDE.md에는 이미 내용이 없는 한@AGENTS.md만 포함됩니다. 내용이 있는 경우AGENTS.md로 이동을 제안합니다.pull_request_template.md는.github/에 위치합니다. 강요하지 말고 제공합니다.
4. 마무리
생성 또는 변경된 파일 목록과 남은 열린 질문을 나열합니다. 사용자에게 다음을 상기시킵니다:
AGENTS.md는 매월 검토하고 정리하며, 특히 모델을 변경할 때 그렇습니다.ARCHITECTURE.md는 분기마다 코드와 대조하여 확인합니다.- 에이전트가 반복하는 실수는 도구 규칙이 되거나, 최후의 수단으로 "Known pitfalls" 아래에 한 줄이 됩니다.