ADR-0002: 에이전트 지침은 AGENTS.md 단일 출처

• 상태: 승인됨
• 날짜: 2026-06-21

맥락

이 저장소는 여러 AI 도구와 함께 쓴다 — Claude Code는 CLAUDE.md를, Codex는 AGENTS.md를 지침으로 읽는다. 같은 규칙을 두 파일에 따로 적으면 표류한다(한쪽만 고쳐지는 문제).

결정

AGENTS.md를 단일 출처(SSOT)로 둔다. - CLAUDE.md는 @AGENTS.md 한 줄로 그 내용을 import 하는 얇은 포인터로만 유지한다. - 폴더 고유 지침이 실제로 필요할 때만 그 폴더에 AGENTS.md(고유 내용) + CLAUDE.md(@AGENTS.md) 쌍을 만든다. 모든 폴더에 두지 않는다. - 중첩 파일에는 그 폴더 고유 내용만 적고, 루트 규칙은 복붙하지 않는다(계층적으로 함께 적용됨).

대안

• CLAUDE.md를 정본으로 — Codex가 읽지 못한다.
• 두 파일에 같은 내용을 복붙 — 동기화가 수작업이라 반드시 표류한다.

결과

• 규칙은 한 곳만 고치면 두 도구에 동시 반영된다.
• import는 1단계(중첩 깊이 제한 내)라 단순하다.
• 새 폴더 지침을 만들 땐 쌍으로 만들어야 한다는 규칙을 지켜야 한다.