레포 구조: 파일마다 답하는 질문 하나

내용 검토: 2026. 09. 23.

결론부터

지침은 AGENTS.md 하나, 지식은 docs/ 아래 스펙·설계·계획 세 층에 두고, 문서마다 답하는 질문을 하나로 고정한다

이 페이지는 레포에 어떤 파일을 두고 각 파일에 무엇을 적는가에 답한다. 구조를 먼저 잡아야 뒤의 페이지에서 말하는 “스펙을 고친다”, “계획을 완료한다”가 어느 파일의 일인지 분명해진다.

이 장에서 처음 나오는 말1개

정본Single Source of Truth: 같은 정보를 고칠 때 손대는 파일 하나. 복사본이 둘이면 어느 쪽이 맞는지 매번 확인해야 한다.

대화에만 남은 결정은 다음 세션에 없다

에이전트 세션은 매번 빈 컨텍스트로 시작한다. “최대 1,000건으로 제한하기로 했다”는 결정이 대화에만 있으면 다음 세션은 그 결정을 모른 채 다른 값을 고르거나 사용자에게 다시 묻는다. Codex에서 정한 것을 Claude Code가 모르는 문제도 같은 원인이다.

해법은 결정의 종류마다 읽을 파일을 정해 두는 것이다. 파일이 정해져 있으면 에이전트는 “어디를 봐야 하는가”를 추측하지 않고, 사람은 “어디를 고쳐야 하는가”를 검색하지 않는다.

파일마다 답하는 질문이 다르다

한 파일이 두 질문에 답하기 시작하면 다른 파일과 내용이 겹치고, 겹친 곳부터 어긋난다. 표의 “답하는 질문” 열이 곧 그 파일의 범위다.

파일	답하는 질문	언제 갱신하는가	에이전트가 언제 읽는가
`AGENTS.md`	이 레포에서 어떻게 일하는가	반복되는 작업 규칙이 바뀔 때	매 세션 자동
`product-specs/`	무엇을 왜 만들고 완료를 어떻게 판정하는가	요구가 바뀔 때	기능을 만들거나 바꿀 때
`design-docs/`	어떻게 만들었고 왜 그렇게 정했는가	작업이 끝나 규약·결정이 확정될 때	그 영역을 고칠 때
`exec-plans/active/`	지금 어떤 순서로 어디까지 왔는가	실행하는 동안 계속	그 작업을 이어받을 때
`verification.md`	무엇을 어떻게 검사하는가	검사 명령·범위가 바뀔 때	변경을 마칠 때

README.md는 사람이 보는 사용법으로 그대로 둔다. 에이전트용 규칙을 README에 섞지 않는다. CLAUDE.md는 두지 않는다. Claude Code는 CLAUDE.md가 없을 때 AGENTS.md를 직접 읽고, 있으면 AGENTS.md를 무시한다. 직접 읽기가 안 되는 세션의 예외는 지침 로딩에서 다룬다.

세 층은 한 방향으로 흐른다

요구는 스펙에서 계획으로 흐르고, 구현하며 확정한 규약은 계획에서 설계로 흐른다. 계획은 스펙을 다시 쓰지 않고 ID로 가리키며, 완료되면 남길 것을 설계로 옮기고 completed/로 간다.

계획을 고치다가 요구 자체를 바꿔야 한다면 스펙을 먼저 고친다. 계획 안에서 완료 조건을 조용히 낮추는 일을 막는 것이 이 방향의 목적이다.

작게 시작하고 필요할 때 층을 연다

모든 레포에 세 층이 다 필요하지는 않다. AGENTS.md·verification.md·exec-plans/로 시작하면 되고, 다음 신호가 보일 때 나머지 층을 연다.

층	여는 신호	없이 지낼 수 있는 경우
`product-specs/`	두 번째 계획이 같은 요구를 다시 적는다. 계획 안에서 “원래 요구가 뭐였지”를 찾는다	요구가 이슈 트래커에 있거나 작업마다 요구가 닫힌다
`design-docs/`	계획을 가로지르는 결정을 매번 옛 계획에서 찾는다	규약이 타입·lint·테스트로 강제되고 결정이 각 계획에 남는다
`exec-plans/`	한 세션에 못 끝내는 작업이 생긴다	모든 작업이 한 세션에 끝나고 PR 설명이 인계를 맡는다

이 사이트도 같은 배치를 쓴다. 요구는 각 덱의 _baseline.md가 맡아 product-specs/가 없고, 기술 규약은 docs/의 작성·검증 지침이 맡아 design-docs/가 없다. 계획만 docs/exec-plans/에 둔다.

이해 확인

CSV 최대 건수를 1,000에서 5,000으로 올리기로 했다. 어느 파일을 고칠까? 요구가 바뀌었으므로 product-specs/task-export.md의 해당 FR을 먼저 고치고, 진행 중 계획이 있으면 그 계획의 완료 조건을 맞춘다. 제한을 구현한 방식이 바뀌면 design-docs/도 고친다.

AGENTS.md가 300줄이 됐다. 무엇이 잘못됐을까? 설명이 지침에 들어왔을 가능성이 크다. 행동 규칙만 남기고 배경·구조 설명은 design-docs/로 옮긴 뒤 읽을 조건과 함께 링크한다.

AGENTS.md 작성법레포의 사실을 조사해 100줄 안팎의 지도를 쓰고, 강제가 필요한 경계는 설정으로 옮긴다.