AGENTS.md 동기화 자동화: PR 템플릿과 pre-commit 훅으로 컨텍스트 로트 잡는 법

솔직히 말씀드리면, 저도 이 문제를 꽤 오래 방치했습니다. 팀에 AI 코딩 에이전트를 도입하고 AGENTS.md를 공들여 작성했는데, 어느 날 Claude Code가 이미 삭제된 src/utils/legacy-api.ts를 아무렇지 않게 임포트하는 코드를 생성하고 있는 걸 발견했습니다. 확인해보니 AGENTS.md는 3개월 전 아키텍처 개편 이전의 폴더 구조를 그대로 설명하고 있었습니다.

이 현상에는 이름이 있습니다. 컨텍스트 로트(Context Rot) — 코드는 매일 바뀌는데 AGENTS.md는 작성 당시의 현실을 고집스럽게 붙들고 있는 상태입니다. 단순한 문서 관리 문제처럼 보이지만, AI 에이전트가 팀의 작업 흐름에 깊이 통합될수록 낡은 AGENTS.md는 잘못된 코드를 조용히 양산하는 버그 제조기가 됩니다. 실제로 동기화 체계를 갖추고 나서부터 AI 생성 코드의 PR 리뷰 지적 건수가 눈에 띄게 줄었고, 신규 팀원 온보딩에 투입하는 시간도 확실히 단축됐습니다.

오늘 이 글을 읽고 나면, PR 템플릿·pre-commit 훅·코드 리뷰 프로세스를 유기적으로 연결해 AGENTS.md 동기화를 자연스러운 팀 워크플로로 만드는 방법을 갖출 수 있습니다. 첫 번째 자동화는 10분이면 팀에 배포할 수 있습니다.

핵심 개념

AGENTS.md가 README.md와 다른 이유

README.md는 사람이 읽습니다. 그래서 조금 낡아도 맥락을 파악해서 스스로 해석합니다. 반면 AGENTS.md는 AI 에이전트가 읽습니다. 에이전트는 작업 시작 시 편집 중인 파일에서 가장 가까운 AGENTS.md를 자동으로 찾아 읽고, 거기 적힌 내용을 그대로 따릅니다. "이 내용이 옛날 거 아닌가?" 하는 판단 없이요.

AGENTS.md는 Claude Code, OpenAI Codex, GitHub Copilot 등 AI 코딩 에이전트에게 프로젝트 맥락을 전달하는 Markdown 파일입니다. 빌드 명령어, 코드 컨벤션, 아키텍처 제약, 금지 패턴 등을 담으며, 에이전트가 작업을 시작할 때 디렉토리를 탐색해 자동으로 읽습니다. OpenAI Codex, Google Jules, Cursor 등 주요 AI 코딩 도구가 동일 형식을 채택하는 방향으로 오픈 표준화 움직임이 진행 중입니다.

드리프트가 생기는 구조적 이유

코드 변경은 매일 일어나고, PR 리뷰는 바쁩니다. AGENTS.md 업데이트를 빠뜨려도 CI가 실패하지 않고, 동료가 지적하지 않으면 아무도 모릅니다. 이게 드리프트가 생기는 근본 원인입니다.

[일반적인 드리프트 발생 패턴]
 
Week 1:  AGENTS.md 작성 — 현재 아키텍처 정확히 반영 ✅
Week 4:  폴더 구조 개편 PR 머지 — AGENTS.md 업데이트 없음 ⚠️
Week 8:  패키지 교체 (axios → fetch) — AGENTS.md 업데이트 없음 ⚠️
Week 12: 에이전트가 삭제된 경로로 임포트 코드 생성 💥
         리뷰어가 잡아내고 재작업 발생

문제는 Week 4와 8에서 이미 시작됐는데, 피해는 Week 12에 가서야 보인다는 점입니다.

계층적 AGENTS.md 구조 — 모노레포를 쓰는 팀이라면

모노레포 환경에서 루트에 AGENTS.md 하나로 모든 도메인을 설명하려는 유혹이 있습니다. 저희 팀도 처음에는 그렇게 했는데, 파일이 점점 길어지면서 관리도 어렵고 에이전트 호출마다 토큰 비용도 늘어났습니다. 에이전트는 코드를 처리할 때마다 AGENTS.md 전체를 입력으로 읽기 때문에, 파일이 길수록 비용이 그대로 올라갑니다.

결국 아래 구조로 갔고, 관리가 훨씬 편해졌습니다.

project/
├── AGENTS.md          # 전사 공통: 커밋 형식, 보안 규칙, CI 명령어
├── backend/
│   └── AGENTS.md      # NestJS 패턴, DB 마이그레이션 규칙
├── frontend/
│   └── AGENTS.md      # Next.js Server Component 규칙, Tailwind 컨벤션
└── infra/
    └── AGENTS.md      # Terraform 패턴, 배포 절차

루트 AGENTS.md가 150~200줄을 초과하기 시작하면 서브디렉토리 분리를 검토해볼 시점입니다. 에이전트는 편집 중인 파일에 가장 가까운 AGENTS.md를 우선 적용하므로, 팀·도메인별 독립적 맥락 관리가 가능해집니다.

실전 적용

예시 1: PR 템플릿에 체크리스트 심기

난이도: 낮음 | 자동화 수준: 낮음 | 초기 설정 시간: 10분

가장 낮은 비용으로 시작할 수 있는 방법입니다. 팀원이 PR을 열 때 자연스럽게 AGENTS.md를 떠올리게 만드는 장치를 PR 템플릿에 추가하는 방식입니다. 처음에는 귀찮게 느껴질 수 있지만, 2~3주 지나면 자연스럽게 습관이 됩니다.

<!-- .github/pull_request_template.md -->
## 변경 사항
(무엇을 왜 변경했는지)
 
## 테스트
- [ ] 단위 테스트 추가/수정
- [ ] 통합 테스트 확인
 
## AGENTS.md 동기화 확인
- [ ] 빌드·테스트 명령어 변경 시 AGENTS.md 업데이트
- [ ] 새 패턴/컨벤션 도입 시 AGENTS.md에 추가
- [ ] 폐기된 패턴 제거 시 AGENTS.md에서 삭제
- [ ] 해당 없음 (코드 로직만 변경)

예시 2: pre-commit 훅으로 자동 감지

난이도: 중간 | 자동화 수준: 높음 | 초기 설정 시간: 30분

PR 템플릿은 사람이 확인해야 합니다. 자동화가 필요하다면 pre-commit 훅이 효과적입니다. 앱 코드가 변경된 디렉토리에 AGENTS.md가 있는데 함께 수정되지 않으면, 커밋 전에 경고를 띄우는 방식입니다.

먼저 아래 스크립트를 .githooks/check-agents-md.sh로 저장합니다.

#!/bin/sh
# .githooks/check-agents-md.sh
#
# AGENTS.md 동기화 여부를 확인하는 소프트 경고 훅 (exit 0 → 커밋 허용)
# 커밋을 차단하는 hard block이 필요하면 마지막 exit 0을 exit 1로 변경
 
changed_dirs=$(git diff --cached --name-only | while IFS= read -r file; do
  dirname "$file"
done | sort -u)
 
for dir in $changed_dirs; do
  if [ -f "$dir/AGENTS.md" ]; then
    if ! git diff --cached --name-only | grep -qF "$dir/AGENTS.md"; then
      echo ""
      echo "⚠️  AGENTS.md 동기화 확인 필요"
      echo "   $dir 의 코드가 변경되었지만 $dir/AGENTS.md 는 수정되지 않았습니다."
      echo "   AGENTS.md가 최신인지 확인하거나,"
      echo "   변경이 불필요한 경우 'git add $dir/AGENTS.md' 후 재커밋해 주세요."
      echo ""
    fi
  fi
done
 
exit 0

이 훅을 팀 전체에 배포하려면 pre-commit 프레임워크와 함께 사용하는 것을 권장합니다. pre-commit은 커밋 전에 실행되는 스크립트를 팀원 모두에게 일괄 관리해주는 오픈소스 도구입니다. .pre-commit-config.yaml에 로컬 훅으로 등록하면 pre-commit install 한 번으로 팀원 전체에 배포됩니다.

# .pre-commit-config.yaml
repos:
  - repo: local
    hooks:
      - id: agents-md-sync-check
        name: Check AGENTS.md sync
        entry: .githooks/check-agents-md.sh
        language: script
        pass_filenames: false
        always_run: true

설정 후 팀원들이 각자 아래를 한 번씩 실행하면 됩니다.

pip install pre-commit
pre-commit install

예시 3: 여러 AI 도구를 쓰는 팀 — symlink로 단일 소스 유지

난이도: 낮음 | 자동화 수준: 중간 | 초기 설정 시간: 15분

Claude Code, Cursor, Codex를 병행 사용하는 팀이라면 CLAUDE.md, .cursorrules, AGENTS.md를 각각 관리하고 싶지 않을 것입니다. 처음엔 "그냥 각각 관리하면 되지 않나?" 싶었는데, 하나라도 업데이트가 누락되면 도구마다 다른 규칙을 따르게 되는 상황이 생깁니다. symlink 패턴이 이 문제를 깔끔하게 해결해줍니다.

프로젝트 루트 디렉토리에서 아래를 실행합니다.

# AGENTS.md를 단일 소스로 설정하고 나머지를 심볼릭 링크로 연결
mv CLAUDE.md AGENTS.md
ln -s AGENTS.md CLAUDE.md
ln -s AGENTS.md GEMINI.md
 
git add AGENTS.md CLAUDE.md GEMINI.md
git commit -m "chore: 단일 소스 AGENTS.md로 통합"

Git은 심볼릭 링크를 네이티브로 추적하므로 팀원이 clone/pull 시 동일한 구조를 얻습니다. 이후 AGENTS.md 하나만 관리하면 됩니다.

주의: ln -s는 현재 디렉토리 기준 상대 경로로 링크를 생성하기 때문에 반드시 프로젝트 루트에서 실행해야 합니다. 다른 경로에서 실행하면 링크가 깨집니다. Windows 환경에서는 심볼릭 링크 생성에 관리자 권한이 필요하거나 Git 설정(core.symlinks=true)이 필요할 수 있습니다.

예시 4: 코드 리뷰 코멘트를 AGENTS.md 개선 신호로 활용

난이도: 낮음 | 자동화 수준: 없음 | 효과: 장기적으로 가장 큰 임팩트

이건 제가 가장 효과적이라고 느낀 방법입니다. 처음엔 "리뷰 코멘트가 AGENTS.md 개선이랑 무슨 상관이지?" 싶었는데, 알고 보면 반복되는 리뷰 코멘트는 AGENTS.md에 아직 없는 규칙을 정확히 가리키는 신호입니다. 같은 지적이 두 번 이상 반복된다면, 그건 AGENTS.md에 추가해야 할 규칙입니다.

<!-- AGENTS.md에 추가하는 방식 예시 -->
 
## 금지 패턴
 
### 절대 하지 않는 것
 
- `axios`를 직접 임포트하지 않습니다. 내부 `src/lib/http-client.ts` 래퍼를 사용합니다.
```typescript
// ❌ 금지
import axios from 'axios';
 
// ✅ 권장
import { httpClient } from '@/lib/http-client';

• any 타입을 사용하지 않습니다. 타입을 모를 경우 unknown 후 타입 가드를 사용합니다.

AI 에이전트 워크플로 자동화 도구를 만드는 HumanLayer 팀이 수백 개의 CLAUDE.md를 분석한 결과, 최고의 파일들은 모두 코드 리뷰 코멘트를 기반으로 수 주에 걸쳐 반복 개선된 것들이었습니다. 한 번에 완벽하게 만들려는 것보다, 리뷰 코멘트를 보며 계속 다듬어가는 접근이 훨씬 효과적입니다.

장단점 분석

장점

단점 및 주의사항

컨텍스트 로트(Context Rot): 코드는 최신 상태인데 AGENTS.md가 과거 상태를 기술하는 현상. 에이전트가 낡은 지침을 따르며 잘못된 임포트 패턴, 폐기된 API 사용, 변경된 폴더 구조 기반 코드를 생성하게 됩니다.

실무에서 가장 흔한 실수

1. "나중에 업데이트하자"로 미루기 — 아키텍처 개편 PR이 머지되는 순간이 AGENTS.md를 업데이트할 최적의 타이밍입니다. 그 순간을 놓치면 기억이 흐려집니다.

2. 중복 내용을 여러 파일에 작성하기 — 루트 AGENTS.md와 서브디렉토리 AGENTS.md에 같은 내용이 있으면 반드시 드리프트가 발생합니다. "한 곳에만" 원칙을 유지하고 나머지는 참조 방식으로 처리하는 것이 좋습니다.

3. 규칙을 산문으로만 설명하기 — 스타일을 설명하는 세 단락보다 실제 코드 예시 하나가 더 효과적입니다. // ❌ 금지와 // ✅ 권장 패턴을 실제 코드로 보여주는 것이 에이전트에게도, 사람에게도 훨씬 명확하게 전달됩니다.

마치며

AGENTS.md 동기화는 기술적 문제이기 이전에 팀 워크플로 설계의 문제입니다. pre-commit 훅과 PR 템플릿으로 자동화의 그물을 치고, 코드 리뷰 코멘트로 지속적으로 개선하는 사이클이 갖춰졌을 때 — 비로소 에이전트가 팀의 진짜 동료로 작동하기 시작합니다.

지금 바로 시작해볼 수 있는 3단계:

1. 오늘 당장 PR 템플릿 업데이트 — .github/pull_request_template.md를 열어 "AGENTS.md 동기화 확인" 체크리스트 항목 3개를 추가해보시면 좋습니다. 10분이면 충분합니다.

2. 이번 주 안에 pre-commit 훅 등록 — 위 예시 스크립트를 .githooks/check-agents-md.sh로 저장하고, git config core.hooksPath .githooks로 설정하거나 pre-commit 프레임워크를 통해 팀 전체에 공유하는 것을 권장합니다.

3. 다음 스프린트 회고 때 5분 점검 — 팀 리더 또는 스크럼 마스터가 "지난 2주간 반복된 AI 코드 리뷰 코멘트 중 AGENTS.md에 추가할 규칙이 있나요?"라는 질문 하나를 아젠다에 넣어보시면 됩니다. 쌓이는 속도가 눈에 보입니다.

팀에서 다른 방식으로 AGENTS.md를 관리하고 있다면 댓글로 공유해 주시면 좋겠습니다. 더 좋은 방법이 있다면 저도 배우고 싶습니다.

다음 글: 좋은 AGENTS.md 규칙의 문법 — "항상 해라 / 먼저 물어봐 / 절대 하지 마라" 형식으로 에이전트의 행동을 정밀하게 제어하는 컨텍스트 엔지니어링 실전 가이드

참고 자료

• AGENTS.md 공식 사이트 | agentsmd.io
• How to write a great agents.md: Lessons from over 2,500 repositories | GitHub Blog
• Custom instructions with AGENTS.md | OpenAI Codex 공식 문서
• How to Build Your AGENTS.md (2026) | Augment Code
• Keep your AGENTS.md in sync — One Source of Truth | Kaushik Gopal
• A good AGENTS.md is a model upgrade | Augment Code Blog
• Writing a good CLAUDE.md | HumanLayer Blog
• Context engineering best practices for AI-powered dev teams | Packmind
• Beyond Prompts: How Git Hooks Steer AI Coding Agents in Production | DEV Community
• AI Coding Tip 014 - Use Nested AGENTS.md Files | DEV Community
• Do you symlink your AGENTS.md and skills to .claude? | SSW Rules
• Quality Gates in the Age of Agentic Coding | Helio