개요

결론부터

지침은 AGENTS.md 하나에, 지식은 스펙·설계·계획 세 층에 두면 두 도구와 여러 세션이 같은 기준으로 일한다

Codex로 정한 결정을 Claude Code가 모르고, 새 세션이 끝난 작업을 다시 하고, 검사 명령이 두 파일에 다르게 적혀 있는 문제에서 출발한다. 원인은 같다. 규칙과 결정이 대화에만 남고 레포에는 없기 때문이다.

이 덱은 Git과 Markdown을 아는 독자가 자신의 레포에 다음을 갖추는 방법을 다룬다.

• 두 도구가 함께 읽는 지침 파일 AGENTS.md 하나
• 요구를 담는 스펙, 규약과 결정을 담는 설계, 순서와 현재 상태를 담는 계획 문서
• 요청 → 구현 → 검증 → 인계 → 재개로 이어지는 작업 흐름

설명용 예시는 가상 업무 서비스의 CSV 내보내기 기능 하나다. 스펙·설계·계획 페이지가 같은 예시를 이어 쓰므로 세 문서가 어떻게 연결되는지 따라갈 수 있다.

레포 구조부터 보기

구성

1. 구조레포 구조

   지침 파일 하나와 문서 세 층. 각 파일이 답하는 질문과 갱신 시점

2. 지침AGENTS.md

   무엇을 적고 무엇을 뺄지, 두 도구가 이 파일을 언제 읽는지

   • AGENTS.md 작성법
   • 지침 로딩
3. 문서스펙 · 설계 · 계획

   요구는 스펙, 규약과 결정은 설계, 순서와 현재 상태는 계획

   • 스펙 문서
   • 설계 문서
   • 계획 문서
4. 흐름요청 · 구현 · 검증 · 인계

   한 작업을 요청부터 다른 도구의 재개까지 끌고 가는 순서

5. 심화선택 심화

   규칙이 갈라지는 monorepo와 공개 레포의 배치 비교

   • Monorepo의 지침 경계
   • 공개 레포의 배치 비교

지금 필요한 일에서 시작하기

지금 필요한 일	읽을 곳
레포에 어떤 파일을 둘지 정한다	레포 구조
AGENTS.md를 새로 쓰거나 고친다	AGENTS.md 작성법
Claude Code가 AGENTS.md를 읽는지 확인한다	지침 로딩
큰 기능의 요구를 정리한다	스펙 문서
구현하며 정한 규약을 남긴다	설계 문서
여러 세션에 걸칠 작업을 시작한다	계획 문서
구현·검증하고 다른 도구로 넘긴다	작업 흐름

이 덱이 다루지 않는 것

두 도구의 설정 항목 전체, API 개발, 모델 성능 비교는 다루지 않는다. 이 사이트 자체의 덱 작성 규칙도 다른 레포에 복사할 대상이 아니다. 공식 문서와 공개 레포를 2026-09-23에 대조했다. Claude Code가 CLAUDE.md 없이 AGENTS.md를 읽는 것은 실제 세션에서 확인했고, 그 밖의 동작은 실측한 결과가 아니다.