AGENTS.md와 문서화 전략

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

Slack 채널에 중요한 아키텍처 결정을 올려놓았습니까? Confluence에 코딩 컨벤션을 정리해 두었습니까? 이 모든 정보는 에이전트에게 존재하지 않습니다.

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

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

❌ 잘못된 패턴
팀 컨벤션 → 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 특화 지침을 추가하는 방식입니다.

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에 명시적으로 기록해야 합니다. 문서는 코드와 동일한 수준으로 관리하고, 자동화된 린팅과 주기적 리뷰로 최신 상태를 유지하세요.