AGENTS.md와 문서화 전략

에이전트에게 보이지 않으면 존재하지 않는다

Slack 채널에 중요한 아키텍처 결정을 올려놓았습니까? Confluence에 코딩 컨벤션을 정리해 두었습니까? 연결된 검색·MCP 도구와 접근 권한이 없다면 에이전트는 그 내용을 읽을 수 없습니다.

에이전트는 컨텍스트 윈도우에 주입된 정보만을 알고 있습니다. 아무리 중요한 규칙이라도 에이전트가 읽을 수 있는 파일에 없다면, 에이전트는 그 규칙을 모르는 채로 작업합니다.

이것이 레포지토리가 단일 권위 소스여야 하는 이유입니다.

❌ 잘못된 패턴
팀 컨벤션 → Slack #engineering 채널
아키텍처 결정 → Confluence 위키
보안 정책 → 이메일 스레드

✅ 올바른 패턴
팀 컨벤션 → AGENTS.md (레포지토리 루트)
아키텍처 결정 → docs/adr/ (Architecture Decision Records)
보안 정책 → SECURITY.md

AGENTS.md vs CLAUDE.md

두 파일은 비슷해 보이지만 목적이 다릅니다.

파일	주체	범위	특징
`AGENTS.md`	팀 전체	에이전트 중립	에이전트 종류 무관한 컨벤션
`CLAUDE.md`	Claude 특화	Claude 전용	Claude 특유 동작 지침
`.cursorrules`	Cursor IDE	해당 IDE	IDE 특화 규칙

실제로는 두 파일을 병행 유지하는 팀이 많습니다. AGENTS.md에 일반 컨벤션을 두고, CLAUDE.md에 Claude 특화 지침을 추가하는 방식입니다.

Codex의 발견 범위와 제한

Codex는 전역 지침 다음에 프로젝트 루트에서 현재 작업 디렉터리까지 지침을 결합합니다. 각 디렉터리에서는 AGENTS.override.md, AGENTS.md, 설정한 fallback 순서로 최대 한 파일을 선택합니다. 현재 디렉터리에 더 가까운 지침이 앞선 지침을 구체화합니다.

결합되는 프로젝트 문서 크기는 project_doc_max_bytes의 제한을 받으며 기본값은 32 KiB입니다. 짧은 진입 문서에서 상세 절차·아키텍처 문서로 연결하고, 필요한 경우 디렉터리별 지침을 사용합니다. 파일을 저장했다는 사실만으로 모든 에이전트 제품이 같은 우선순위·로딩 방식으로 처리한다고 가정하지 않습니다.

AGENTS.md는 모델이 읽는 지침입니다. 실제 파일·네트워크 권한이나 브랜치 보호는 샌드박스·실행 정책·CI에서 강제합니다.

AGENTS.md 필수 섹션

1. 프로젝트 개요

## 프로젝트 개요
이 레포지토리는 [서비스명] 의 [설명] 입니다.

- **언어**: TypeScript 5.x (strict mode)
- **런타임**: Node.js 20 LTS
- **패키지 매니저**: pnpm 9
- **테스트 프레임워크**: Vitest

## 주요 디렉토리 구조
src/
  agents/     # 에이전트 구현체
  tools/      # 도구 정의
  harness/    # 하네스 코어
tests/        # 테스트 파일 (src/ 미러링)

2. 코딩 컨벤션

## 코딩 컨벤션

### 필수 규칙
- 모든 함수는 명시적 반환 타입 선언
- `any` 타입 사용 금지 (unknown + 타입 가드 사용)
- 불변성 원칙: 객체/배열 직접 수정 금지, 항상 새 값 반환
- 에러는 반드시 처리 (빈 catch 블록 금지)

### 네이밍
- 함수: camelCase 동사로 시작 (createUser, fetchData)
- 컴포넌트: PascalCase (UserCard, DataTable)
- 상수: SCREAMING_SNAKE_CASE (MAX_RETRY_COUNT)
- 타입/인터페이스: PascalCase, I 접두사 금지

3. 에이전트 권한 범위

## 에이전트 권한 범위

### 허용
- src/, tests/ 파일 읽기/쓰기
- pnpm test, pnpm build 실행
- git add, git commit (main 브랜치 제외)

### 금지
- .env 파일 수정
- production 데이터베이스 쿼리
- 외부 API 직접 호출 (테스트 환경에서는 mock 사용)
- git push --force
- package.json dependencies 수정 (별도 승인 필요)

4. 작업 수행 패턴

## 작업 수행 패턴

### 새 기능 구현 순서
1. tests/ 에 실패하는 테스트 먼저 작성
2. src/ 에 최소 구현으로 테스트 통과
3. pnpm test 로 전체 테스트 확인
4. pnpm build 로 빌드 확인
5. 커밋 메시지: `feat: [기능명] - [간략 설명]`

### 버그 수정 순서
1. 버그를 재현하는 테스트 작성
2. 수정 구현
3. 모든 관련 테스트 통과 확인

5. 금지 패턴 목록

에이전트가 자주 저지르는 실수를 명시적으로 나열합니다.

## 금지 패턴

### 절대 하지 말 것
- console.log를 프로덕션 코드에 남기기 (logger 모듈 사용)
- TODO 주석을 코드에 남기기 (이슈 트래커에 등록)
- 테스트 없이 src/ 파일 수정
- 하드코딩된 URL, 포트, 시크릿 값
- 중첩 depth 4 이상의 if/else

### 주의해야 할 패턴
- Promise 체이닝 대신 async/await 사용
- 에러 메시지에 스택 트레이스 노출 금지 (외부 API 응답)

CLAUDE.md 패턴

Claude 특화 지침은 CLAUDE.md에 별도로 관리합니다.

## 이 프로젝트 정보
[AGENTS.md 내용 요약 또는 include 참조]

## Claude 특화 지침

### 작업 시작 전
- 변경할 파일을 먼저 Read 도구로 읽기
- 관련 테스트 파일 확인
- 기존 패턴 파악 후 동일하게 따르기

### 불확실할 때
- 추측하지 말고 Ask 도구 또는 메시지로 명확화 요청
- 여러 해석이 가능하면 가장 단순한 것 선택

### 완료 기준
- pnpm test 통과
- pnpm build 통과
- console.log 없음
- TypeScript 에러 없음

문서 유효성 유지하기

문서가 오래되면 에이전트를 오히려 혼란스럽게 합니다.

전략	방법
린팅 자동화	`markdownlint` + CI로 형식 강제
주기적 리뷰	스프린트마다 AGENTS.md 검토 항목 추가
버전 태깅	`# AGENTS.md v1.3 - 2026-01` 헤더 추가
변경 알림	AGENTS.md PR은 팀 전체 리뷰 필수 규칙

요약

에이전트는 레포지토리만 볼 수 있습니다. 따라서 팀의 모든 암묵지를 AGENTS.md와 CLAUDE.md에 명시적으로 기록해야 합니다. 문서는 코드와 동일한 수준으로 관리하고, 자동화된 린팅과 주기적 리뷰로 최신 상태를 유지하세요.