서론

Chrome / Firefox 확장 프로그램을 개인 개발할 때, Codex와 Claude Code 모두에게 동일한 리포지토리(Repository)를 다루게 했다. 처음에는 각각의 진입점인 AGENTS.md와 CLAUDE.md에 구현 규칙이나 verify 명령어를 작성했다.

하지만 확장의 구성이 바뀔 때마다 한쪽만 업데이트되고, 다른 한쪽의 규칙은 오래된 상태로 남는 문제가 발생했다. 이 기사에서는 에이전트별 파일에 상세 규칙을 중복해서 작성하는 것을 그만두고, .agents/rules/를 공통 단일 진실 공급원(Single Source of Truth)으로 삼기로 한 판단에 대해 기술한다.

대상 리포지토리는 harness17/kindle-series-sale-tracker 입니다.

문제점: 진입점마다 어긋나는 규칙

이 확장 프로그램은 Amazon.co.jp의 Kindle 소장 정보(蔵書情報)를 바탕으로 시리즈 후보나 속권·세일 상태를 확인한다. 구현 경계는 나름대로 세분화되어 있다.

• content script는 동일 출처(Same-origin) 취득 및 저장을 담당한다.
• background / offscreen은 백그라운드 조회를 담당한다.
• popup / options는 저장된 결과의 표시를 담당한다.
• Chrome은 offscreen document를, Firefox는 background scripts에서 DOMParser를 사용한다.

이러한 규칙을 처음에는 Codex용 AGENTS.md와 Claude Code용 CLAUDE.md 양쪽에 모두 작성했다. 단기적으로는 읽기 편하지만, 업데이트 시점에 파괴되었다.

예를 들어 verify 명령어가 늘어났을 때, 한쪽 파일만 새로운 개수로 업데이트되고 다른 한쪽은 옛날 상태로 남는다. 한쪽 에이전트는 "3개를 통과하면 충분하다"고 판단하고, 다른 한쪽은 "5개가 필요하다"고 판단한다. 구현의 안전성을 높이기 위한 규칙이 오히려 확인 누락의 원인이 되고 있었다.

판단: 에이전트별 파일을 단일 진실 공급원으로 삼지 않는다

이 문제는 "양쪽을 잊지 않고 업데이트한다"는 방식으로는 해결할 수 없다고 판단했다. 구현 변경 시마다 두 파일을 동기화하는 운영 방식은 시간이 지나면 반드시 누락된다.

따라서 구현·데이터·검증·공개의 계약(Contract)은 .agents/rules/에 집약하고, AGENTS.md와 CLAUDE.md는 진입점과 색인(Index) 역할만 하도록 했다.

현재 구성은 다음과 같다.

.agents/rules/
├── amazon-boundary.md
├── architecture-and-data.md
...

포인트는 AGENTS.md와 CLAUDE.md의 차이를 "읽는 에이전트의 차이"로 한정 짓는 것이었다. 구현 계약 그 자체는 에이전트 고유의 것으로 만들지 않는다.

구현: AGENTS.md는 색인으로 만든다

AGENTS.md에는 작업 시작 시 읽어야 할 공통 규칙으로의 링크를 배치했다. 구현 규칙의 본문을 이곳에 다시 복사하지 않는다.

## 공통 규칙
- 항상 읽을 것: [.agents/rules/architecture-and-data.md](.agents/rules/architecture-and-data.md)
- 항상 읽을 것: [.agents/rules/verification.md](.agents/rules/verification.md)
...

여기서 명시하는 것은 어떤 규칙을 읽을 것인가와 어디를 단일 진실 공급원으로 삼을 것인가뿐이다. 예를 들어 "어떤 verify를 통과할 것인가"는 AGENTS.md에 직접 쓰지 않고 .agents/rules/verification.md로 모은다.

구현: CLAUDE.md도 공통 단일 진실 공급원으로 회귀

Claude Code 측의 CLAUDE.md도 구현 규칙을 떠안지 않는 형태로 만들었다. Claude Code 고유의 협업 규칙은 남겨두되, 구현 계약은 AGENTS.md와 .agents/rules/로 되돌린다.

# CLAUDE.md
Claude Code가 이 리포지토리에서 작업할 때의 진입점.
## 먼저 읽을 것
...

이렇게 나누면 Claude Code 전용의 handoff나 협업 규칙은 CLAUDE.md 측에 남길 수 있다. 반면 데이터 경계나 verify 개수와 같은 구현 계약은 .agents/rules/만 업데이트하면 된다.

공통 단일 진실 공급원에 넣은 것

.agents/rules/architecture-and-data.md

에는 모듈 경계(Module Boundary)와 백그라운드 질의 계약(Background Query Contract)을 배치했다. 이는 Codex에서도 Claude Code에서도 동일한 판단으로 동작하기를 바라는 내용이기 때문이다.

## 백그라운드 질의 계약 (Background Query Contract)
- eligible series는 completed / excluded를 제외하고, 유한한 `highestVolume`을 가진 것으로 한다.
- 1회 실행 시 대상 전체를 순회하며, 내부적으로 `CHUNK_SIZE` 단위로 처리한다. chunk 사이즈를 "alarm 1회의 총 상한"으로 오해하지 말 것.
...

.agents/rules/verification.md

에는 확인 명령어를 정리했다.

node .\verify-kindle-library.mjs
node .\verify-catalog-probe.mjs
node .\verify-series-card.mjs
...

이 5개를 진입 파일(Entry File)에 중복해서 복사하지 않는다. 향후 verify가 늘어나더라도 업데이트해야 할 곳은 verification.md 하나뿐이다.

버린 안

처음에 생각한 것은 AGENTS.md와 CLAUDE.md 모두를 매번 동일한 내용으로 업데이트하는 운영 방식이었다. 하지만 이는 구현 변경이 일어날 때마다 "다른 한쪽도 업데이트해야 한다"는 기억에 의존하게 된다.

다음으로, 한쪽을 다른 한쪽의 완전한 복사본으로 만드는 안도 고려했다. 다만, Claude Code에는 Claude Code 고유의 협업 규칙이 있고, Codex에는 Codex용 작업 진입점이 있다. 완전 복사를 하게 되면 고유 규칙까지 섞여 오히려 가독성이 떨어지게 된다.

채택한 것은 다음과 같은 분리였다.

종류	위치
구현 · 데이터 · 검증 · 공개 계약	.agents/rules/
...	CLAUDE.md / .claude/rules/

원본(Source of Truth)을 하나로 유지하면서, 진입점별 차이는 남겨두는 형태이다.

확인한 사항

이번 구성에서는 다음 사항을 확인했다.

• AGENTS.md가 .agents/rules/architecture-and-data.md 및 .agents/rules/verification.md를 상시 참조하고 있음
• CLAUDE.md가 구현 계약을 AGENTS.md 및 .agents/rules/로 돌려보내고 있음
• .agents/rules/에 amazon-boundary.md, architecture-and-data.md, release-and-store.md, verification.md가 있음
• verify 명령어 목록이 verification.md에 집약되어 있음
• Amazon 취득 및 공개물의 경계가 구현 진입점이 아닌 토픽별 규칙으로 나뉘어 있음

이로써 구현 변경 시 "어느 에이전트용 파일을 업데이트했는가"를 고민할 필요가 줄어들었다. 확인하고 싶은 계약은 .agents/rules/를 보면 된다.

요약

AI 에이전트를 여러 개 사용하면 진입 파일도 여러 개가 된다. 하지만 진입점이 여러 개인 것과 구현 규칙의 원본이 여러 개인 것은 별개의 문제였다.

이번 학습을 통한 세 가지 교훈은 다음과 같다.

• AGENTS.md와 CLAUDE.md에 동일한 상세 규칙을 작성하지 않는다.
• 구현 계약은 .agents/rules/와 같은 공통 원본으로 모은다.
• 에이전트 고유 파일은 진입점, 색인, 고유 규칙으로 역할을 한정한다.

규칙의 드리프트(Drift)는 주의력이 아닌 구조를 통해 줄이는 것이 더 안정적이었다.

참고 링크

Discussion