DEV Community

GyeongSeon
GyeongSeon

Posted on

AI 에이전트 개발 문서 관리 가이드

#agents #ai #documentation #softwaredevelopment

문서는 레포 안에 두고, 코드와 함께 버전 관리하며, 수명과 적용 범위에 따라 계층을 나눈다. 에이전트는 매 세션 기억 없이 시작하므로 레포에 적힌 것만 사실로 취급하고, 필요한 문서만 골라 읽게 설계한다.

  1. 문서 계층 문서는 얼마나 오래 유효한지를 기준으로 나눈다. 상시 규칙은 짧게, 상세 내용은 docs/에 두고 가리키기만 한다. 계층 파일 예시 내용 변경 빈도 상시 규칙 CLAUDE.md (루트 + 모듈별) 빌드/테스트 명령, 컨벤션, 금지사항, 아키텍처 요약 낮음 요구사항/스펙 docs/features// 기능별 요구사항, 수용 기준, 요구사항 ID 중간 의사결정 docs/adr/NNNN-.md 결정 이유와 검토한 대안 추가만 함 작업 계획 docs/features/*/tasks.md 단계와 체크리스트 작업 종료 시 폐기 운영 docs/runbooks/, docs/postmortems/ 장애 대응, 회고, 재발 방지 사건 발생 시 변경 이력 CHANGELOG.md, git log 언제 무엇이 바뀌었나 매 릴리스 • CLAUDE.md는 매 세션 컨텍스트에 들어가므로 100~200줄 이내로 유지한다. • 상세 문서는 경로만 적고 "필요할 때 읽을 것"으로 안내한다.
  2. 요구사항 변경 대응 요구사항이 바뀌면 코드보다 스펙 문서를 먼저 고친다. 순서는 스펙 변경 → 계획 → 구현이다.
  3. 스펙 수정: requirements.md를 먼저 바꾸고, 에이전트에게 스펙 diff를 리뷰하게 한다.
  4. 요구사항 ID 추적: REQ-ORDER-CANCEL-001 같은 ID를 스펙, 테스트 이름, 커밋 메시지에 함께 쓴다. "이 요구사항에 영향받는 코드와 테스트를 찾아줘"가 가능해진다.
  5. 덮어쓰지 않고 상태 표시: Status: Active / Deprecated (ADR-0014로 대체). 결정이 바뀌면 새 ADR을 만들고 Supersedes로 연결한다.
  6. 같은 PR에 포함: 코드 변경과 문서 갱신을 한 PR에 넣고, PR 체크리스트에 문서 갱신 여부를 둔다.
  7. 오래된 문서 삭제: 틀린 문서는 없는 문서보다 해롭다. 끝난 계획은 archive/로 옮기거나 지운다.
  8. 운영 중 개선과 장애 운영에서 얻은 교훈은 문서 한 줄보다 강제되는 장치로 바꾼다. • 장애 발생: 포스트모템 → 재발 방지책. 재발 방지책은 테스트, 린트 규칙, Hook 형태를 우선한다. • 에이전트가 같은 실수를 반복하면 즉시 CLAUDE.md에 규칙 한 줄 추가 (예: "Oracle 페이징은 ROWNUM 대신 OFFSET FETCH 사용"). • 주기적으로 CLAUDE.md를 정리한다. 쓸모없는 규칙은 지우고 겹치는 규칙은 합친다. 에이전트에게 "현재 코드와 맞지 않는 규칙을 찾아줘"로 점검을 맡길 수 있다.
  9. 일관된 결과 얻기 명확한 지시, 고정된 작업 흐름, 기계적 강제 장치, 작은 컨텍스트가 일관성을 만든다. 영역 방법 지시 수용 기준을 구체적으로 ("결제 후 30분 이내만 취소, 초과 시 409 + ORDER_CANCEL_EXPIRED"), 기존 코드를 참고 예시로 지정 작업 흐름 탐색 → 계획(Plan 모드) → 구현 → 검증. 큰 작업은 계획을 파일로 저장 실행 가능한 스펙 테스트를 먼저 쓰게 하고 통과할 때까지 구현 (TDD) 반복 절차 Slash command, Skill로 고정 (/new-api, /review, /spec-new) 강제 장치 Hooks로 포맷/린트/테스트 자동 실행. 반드시 지킬 규칙은 Hook이나 CI로 리뷰 서브에이전트가 별도 컨텍스트에서 스펙 대비 리뷰 컨텍스트 작은 작업 단위, 주제가 바뀌면 /clear
  10. 아키텍처 정보 배치 아키텍처 정보는 적용 범위와 가장 가까운 위치에 둔다. 전체 공통은 위에, 모듈별로 다른 구조는 그 모듈 안에 둔다. 위치 범위 로드 시점 조직 관리 정책 CLAUDE.md 회사 공통 표준 항상 ~/.claude/CLAUDE.md 개인 선호 항상 repo/CLAUDE.md 프로젝트 전체 아키텍처 요약과 모듈 지도 세션 시작 repo/module-x/CLAUDE.md 해당 모듈 고유 구조 그 디렉터리 작업 시 .claude/rules/*.md (경로 조건) 특정 경로 패턴 해당 경로 작업 시 (버전별 지원 확인) docs/architecture/ 상세 설계 (C4, 모듈 관계, 공통 규칙) 필요할 때 읽기 모듈 CLAUDE.md 작성 원칙: • 패키지 구조와 기능 추가 순서를 적는다 (예: 헥사고널 domain → port → service → adapter). • 루트 공통 규칙과 다른 점(예외)을 명시적으로 선언한다. • "하지 말 것"도 적는다 (예: admin-batch에 헥사고널 적용 금지). • 기준이 되는 참고 구현 파일을 지정한다. • 이유는 ADR 번호로 연결한다. 여러 레포 공통 표준은 관리 정책 CLAUDE.md, 별도 standards 레포, Skill/플러그인으로 배포한다. 각 레포에는 "따르지 않는 부분"만 적는다. 패키지 의존 규칙은 ArchUnit 테스트로 강제한다. 효과가 큰 조합은 문서(의도) + ArchUnit(강제) + 참고 구현(예시)이다. @ArchTest static final ArchRule domainIsPure = noClasses() .that().resideInAPackage("..order.domain..") .should().dependOnClassesThat() .resideInAnyPackage("org.springframework..", "jakarta.persistence.."); 구조 변경 순서: ADR 작성 → 모듈 CLAUDE.md 수정 → ArchUnit 수정 → 코드 변경, 모두 같은 PR.
  11. ADR (Architecture Decision Record) ADR은 기술적 결정을 왜 그렇게 했는지 결정 하나당 문서 한 장으로 남기는 기록이다. 에이전트가 의도된 구조를 "통일"한다며 되돌리는 것을 막는다. • 결정 1개 = 파일 1개, 번호를 순서대로 부여 (docs/adr/0011-admin-batch-layered.md). • 추가만 하고 수정하지 않는다. 결정이 바뀌면 새 ADR을 쓰고 Superseded by / Supersedes로 연결한다. • 한 페이지 이내로 짧게 쓴다. 템플릿은 MADR이 널리 쓰인다. • 대상: 프레임워크/DB 선택, 패키지/모듈 구조, 트랜잭션·에러·인증 같은 공통 정책, 표준에서 벗어나는 예외. # ADR-0011: admin-batch는 레이어드 구조와 MyBatis를 유지한다
  12. Status: Accepted (Proposed / Accepted / Deprecated / Superseded by ADR-XXXX)
  13. Date: 2026-10-22 ## Context 대량 조회/집계 SQL 위주, 도메인 로직이 얇고 Oracle 힌트 튜닝이 필요하다. ## Decision 레이어드 + MyBatis 유지. 헥사고널과 JPA는 적용하지 않는다. ## Alternatives
  14. 헥사고널 + JPA: 계층만 늘고 SQL 튜닝이 어려움 ## Consequences
  15. 장점: SQL 튜닝 용이 / 단점: 모듈 간 구조 차이
  16. 재검토 조건: 복잡한 도메인 규칙이 늘어나면 Claude Code와 쓸 때: • 모듈 CLAUDE.md에는 규칙 한 줄 + ADR 번호만 둔다. • 논의 내용을 주고 ADR 초안을 쓰게 하되, 결정과 대안 평가는 사람이 검토한다. • "구조를 바꾸기 전 관련 ADR을 확인하고, 충돌하면 멈추고 알릴 것"을 규칙에 둔다. • adr/README.md에 현재 유효한 결정만 한 줄씩 요약한다.
  17. 스펙 문서 종류와 폴더 구조 시스템 전체 문서는 종류별로, 기능 문서는 기능 폴더별로 묶는다(하이브리드). 기능 하나는 requirements → design → tasks 3단으로 만든다. 분류 문서 답하는 질문 형식 무엇을/왜 요구사항 (PRD) 누구의 어떤 문제를 푸는가 Markdown 무엇을/왜 수용 기준 무엇을 만족하면 완료인가 Given-When-Then, EARS 무엇을/왜 비기능 요구사항 (NFR) 성능, 가용성, 보안 기준 Markdown (수치) 무엇을/왜 용어집 도메인 용어의 의미 Markdown 표 어떻게 기술 설계 (Design Doc) 구조, 흐름, 트랜잭션, 예외 Markdown + Mermaid 어떻게 API 명세 엔드포인트, 요청/응답, 에러코드 OpenAPI 어떻게 이벤트 명세 비동기 메시지 구조 AsyncAPI, JSON Schema 어떻게 데이터 모델 테이블, 인덱스, 제약 ERD, 마이그레이션 어떻게 외부 연동 명세 인터페이스, 타임아웃, 재시도 Markdown 어떻게 ADR 왜 이 방식을 택했나 Markdown 순서 구현 계획 (tasks) 어떤 단계로 구현하나 체크리스트 확인 테스트 시나리오 수용 기준을 어떻게 검증하나 Markdown, 테스트 코드 운영 Runbook, Postmortem 장애 대응과 재발 방지 Markdown repo/ ├── CLAUDE.md # 문서 지도 + 작업 규칙 ├── docs/ │ ├── README.md # 문서 인덱스 │ ├── product/ (vision.md, glossary.md) │ ├── architecture/ (overview.md, conventions.md, nfr.md, data-model.md) │ ├── adr/ (README.md, 0001-*.md ...) │ ├── features/ │ │ └── ORDER-cancel/ (requirements.md, design.md, tasks.md, test-scenarios.md) │ ├── integrations/ │ ├── runbooks/ , postmortems/ │ ├── templates/ (requirements, design, tasks, adr) │ └── archive/ ├── api/openapi.yaml # API 명세 원본 ├── order-service/ │ ├── CLAUDE.md # 모듈 아키텍처 │ └── src/main/resources/db/migration/ # DDL 원본 └── .claude/commands/ (spec-new.md, spec-design.md, spec-tasks.md) 문서 관리 규칙: • 기계가 읽는 스펙(OpenAPI, 마이그레이션)은 원본 하나만 두고 Markdown에 다시 옮겨 적지 않는다. • frontmatter에 id, status(Draft / Approved / Implemented / Deprecated), owner, updated, related를 둔다. • 요구사항 ID(REQ-ORDER-CANCEL-001)를 테스트 @DisplayName과 커밋에도 쓴다. • 생명주기: 템플릿 복사(Draft) → 검토(Approved) → 구현(Implemented, tasks 정리) → 폐기(Deprecated, archive/ 이동).
  18. 컨텍스트와 토큰 관리 문서가 많다고 토큰을 많이 쓰는 것은 아니다. 컨텍스트를 차지하는 것은 항상 로드되는 것과 실제로 읽은 것뿐이므로, 필요한 문서만 골라 읽게 하는 점진적 공개 구조를 만든다. 현재 사용량은 /context로 측정한다. 계층 예시 전략 항상 로드 루트 CLAUDE.md, @import 파일, MCP 도구 정의, Skill 설명 CLAUDE.md는 목차만, @import 최소화(시작 시 로드됨), 미사용 MCP 끄기 조건부 로드 하위 CLAUDE.md, 경로 규칙, Skill 본문 모듈 내용과 가끔 쓰는 절차는 여기로 필요 시 읽기 docs/ 스펙, ADR, 설계 docs/README.md 인덱스(한 줄 요약 + 읽어야 할 때), 문서 상단 TL;DR, 검색 가능한 ID 규칙 포맷, 의존 방향, 응답 형식 기계 검사 가능한 것은 Hook, ArchUnit, Spotless로 옮기고 문서에서 삭제 대화 누적 읽은 파일, 명령 출력 서브에이전트로 탐색 후 요약만 받기, 기능당 세션 1개, /clear, tasks.md로 이어 가기, /compact에 남길 내용 지정 유지보수 완료/폐기 문서 archive/는 요청 시에만 읽기, 중복 제거, adr/README.md는 유효한 결정만 # 나쁜 예: 시작할 때 전부 로드됨 @docs/architecture/overview.md

좋은 예: 필요할 때만 읽게 안내

  • 모듈 간 의존 관계를 바꿀 때만 docs/architecture/overview.md 를 읽을 것 크기 예산: CI에서 CLAUDE.md 200줄 제한을 검사하고, 기능 스펙 한 파일이 300줄을 넘으면 분할을 검토한다. 분기마다 에이전트에게 중복이나 코드와 어긋난 내용을 점검하게 한다.
  • 피해야 할 패턴 • CLAUDE.md 하나에 모든 내용을 넣어 수백 줄로 키우기 • 대화로만 요구사항을 전달하고 문서에 남기지 않기 (다음 세션에서 사라짐) • 코드만 바꾸고 스펙과 ADR은 그대로 두기 • 모듈별 예외를 적지 않아 에이전트가 다른 모듈 패턴을 섞게 두기 • 문서 종류별 폴더만 두어 기능 하나를 보려면 여러 폴더를 오가게 하기 • API나 DDL을 Markdown에 다시 옮겨 적기 (원본과 어긋남) • 끝난 tasks.md나 폐기된 스펙을 그대로 두기 • 큰 문서를 @import로 항상 로드하기 • 꼭 지켜야 하는 규칙을 문서로만 관리하기 (Hook, 테스트, CI로 강제)

Top comments (0)