AI와 협업하는 문서 작성 프로세스
소스 스캔→초안→결정적 검증→에이전트 smoke test→소유자 리뷰의 문서 운영 루프
핵심 요약
- 초안은 AI가 만들고, 근거 수집과 검증은 결정적인 운영 루프로 고정합니다.
- 라이프사이클은 소스 스캔 → 문서 설계 → AI 초안 → 결정적 검증 → 에이전트 smoke test → 소유자 리뷰 → 발행/모니터링 순서입니다.
- 소스 스캔을 먼저 하지 않으면 AI가 없는 명령어·API로 빈칸을 채우니, "추정한 내용"과 "확인 불가 내용"을 따로 표기하게 합니다.
- 링크·타입·OpenAPI·코드 블록·파일 경로·명령어 일치는 코드로 검증합니다.
- 회의록·제안서 같은 비즈니스 문서도 검증 소스만 코드에서 녹취·CRM·정책으로 바꿔 같은 루프를 적용합니다.
문서를 처음부터 끝까지 혼자 쓰면 느리고, AI에게 초안을 전부 맡기면 위험합니다. 에이전틱 문서화에서는 AI가 초안을 만들고, 근거 수집과 검증은 결정적인 루프로 고정합니다.
이 장에서는 문서 작성을 "작성"이 아니라 "검증 가능한 운영 루프"로 설계합니다.
새로운 문서 라이프사이클
| 단계 | 주체 | 핵심 활동 | 산출물 |
|---|---|---|---|
| 소스 스캔 | AI + 사람 | 코드, 스펙, 기존 문서, 공식 문서 확인 | 근거 목록 |
| 문서 설계 | 사람 | 대상, 표면, 소유자, 검증 방법 결정 | 문서 설계 시트 |
| AI 초안 | AI | 템플릿에 맞춰 초안 생성 | MD/MDX 초안 |
| 결정적 검증 | 자동화 | 링크, 스키마, 코드 블록, 타입체크 | CI 결과 |
| 에이전트 smoke test | AI + 사람 | 에이전트가 문서를 실제로 읽고 지침을 따르는지 확인 | 실패 사례 |
| 소유자 리뷰 | 사람 | 사실·권한·보안·톤 최종 확인 | 승인 |
| 발행/모니터링 | CI + owner | 배포, freshness, 드리프트 감지 | 업데이트 이슈 |
초안과 검증을 분리
AI 초안은 생산성 도구입니다. 검증은 별도 단계입니다. 존재하지 않는 API, 낡은 명령어, 깨진 링크, 과한 권한 설명은 초안 단계에서 자주 섞입니다.
1단계: 소스 스캔
문서 초안을 만들기 전에 근거부터 수집합니다. 이 단계가 빠지면 AI는 그럴듯한 일반론으로 빈칸을 채웁니다.
## Source Scan
확인할 것:
- 코드: `src/api/**`, `app/api/**`
- 스펙: `openapi/**`, `schema/**`
- 운영 문서: `docs/runbook/**`
- 프로젝트 규칙: `AGENTS.md`, `CLAUDE.md`, `.claude/rules/**`
- 관련 Skill: `.agents/skills/**/SKILL.md`
- 외부 공식 문서: [링크]
금지:
- 실제 파일에 없는 명령어를 만들지 않는다.
- 공식 문서를 보지 않고 최신 버전을 추정하지 않는다.
- 기존 문서와 충돌하는 규칙을 추가하지 않는다.2단계: 문서 설계
먼저 "어떤 표면에 둘지"를 결정합니다.
| 질문 | 선택지 |
|---|---|
| 항상 읽혀야 하는가 | AGENTS.md, CLAUDE.md |
| 특정 작업에서만 필요한가 | Skill, runbook |
| 외부 시스템의 최신 컨텍스트인가 | MCP Resource |
| 사람이 첫 화면에서 봐야 하는가 | README, docs page |
| 구조화된 계약인가 | OpenAPI, JSON Schema |
| 보안·권한 검토가 필요한가 | security chapter, owner review |
문서 설계 시트
## Document Design
- 목적:
- 주요 독자: 사람 / 코딩 에이전트 / RAG / MCP 클라이언트
- 배치 위치:
- 소유자:
- 참조 소스:
- 반드시 포함할 프로젝트 고유 정보:
- 제외할 범용 설명:
- 검증 명령:
- smoke test 프롬프트:
- freshness 기준:3단계: AI 초안 생성
초안 프롬프트에는 근거, 템플릿, 검증 기준을 함께 줍니다.
다음 소스만 근거로 문서 초안을 작성해줘.
소스에 없는 명령어, API, 버전, 정책은 만들지 마.
소스:
- [파일/링크 목록]
문서 위치:
- docs/api/orders.md
대상:
- 사람 개발자 + 코딩 에이전트
형식:
- frontmatter 포함
- 표, 코드 블록, 완료 조건 포함
- 기본 개념 설명 생략
검증:
- `pnpm openapi:check`
- `pnpm test orders`
출력 후 마지막에 "추정한 내용"과 "확인 불가 내용"을 따로 적어줘.4단계: 결정적 검증
AI 검토만으로는 부족합니다. 자동화할 수 있는 검증은 코드로 고정합니다.
| 검증 | 예시 |
|---|---|
| 링크 | pnpm docs:links |
| 타입/빌드 | pnpm typecheck, pnpm build |
| OpenAPI | pnpm openapi:lint, pnpm openapi:diff |
| 코드 블록 | shellcheck, doctest, markdown code runner |
| frontmatter | 커스텀 lint |
| 파일 경로 | 문서에 적힌 경로 존재 여부 검사 |
| 명령어 | package.json scripts와 문서 명령 대조 |
5단계: 에이전트 smoke test
문서가 "맞는 말"이어도 에이전트가 실제로 잘 못 쓰면 실패입니다.
프로젝트 규칙 smoke test
이 저장소에서 API 라우트를 수정한다고 가정하고,
어떤 파일을 읽고 어떤 검증 명령을 실행해야 하는지 말해줘.
파일은 수정하지 마.확인할 것:
- 에이전트가
AGENTS.md와CLAUDE.md의 규칙을 올바르게 요약하는가 - 존재하지 않는 명령어를 만들지 않는가
- 금지사항을 작업 계획에 반영하는가
- 하위 디렉토리 규칙이 전역 규칙을 의도대로 덮는가
API 문서 smoke test
이 API 문서만 보고 `POST /orders` 호출 코드를 작성한다면
필요한 인증, 요청 body, 오류 처리를 어떻게 구현해야 하는지 설명해줘.
추측한 내용은 별도 표시해줘.확인할 것:
- 인증 방식과 권한을 추측하지 않는가
- 요청/응답 스키마를 빠뜨리지 않는가
- 에러 코드를 처리하는가
- breaking change 여부를 확인하는가
Skill smoke test
`release-check` Skill을 사용해 현재 diff를 검토한다고 가정해줘.
실행할 명령과 출력 형식을 말하되, 실제 파일은 수정하지 마.확인할 것:
- Skill이 의도한 상황에서만 호출되는가
- supporting file을 필요할 때만 읽는가
- side effect가 필요한 작업에서 승인 절차를 언급하는가
도구별 워크플로우
# CLAUDE.md
@AGENTS.md
## Documentation
- 문서 변경 전 관련 코드와 기존 문서를 먼저 읽는다.
- MDX 변경 후 `pnpm --filter handbook run typecheck`를 실행한다.
- 긴 반복 절차는 `.agents/skills/`로 분리한다.docs/api/orders.md를 갱신해줘.
먼저 관련 route, OpenAPI, 기존 문서를 읽고 근거 목록을 보고한 뒤 초안을 작성해.비즈니스 문서에도 같은 루프 적용
회의록, 제안서, 보고서에도 같은 원칙을 적용합니다. 검증 소스가 코드 대신 녹취, CRM, 재무 모델, 공식 정책으로 바뀔 뿐입니다.
다음 회의 녹취와 CRM 메모만 근거로 회의록을 작성해줘.
출력:
1. 결정 사항
2. 액션 아이템
3. 미확인 쟁점
4. 다음 회의에서 확인할 질문
금지:
- 참석자가 말하지 않은 결정을 만들지 않는다.
- 담당자나 기한을 추정하지 않는다.AI 생성 문서의 흔한 문제
| 문제 | 증상 | 해결법 |
|---|---|---|
| 환각 | 존재하지 않는 API, 명령어, 파일 경로 | source scan을 선행하고 "확인 불가" 표시 |
| 과잉 설명 | 범용 개념까지 장황하게 설명 | 프로젝트 고유 정보만 남김 |
| 구조 불일치 | 템플릿과 다른 형식 | 템플릿을 프롬프트에 포함 |
| 날짜 오류 | 과거 정보를 최신으로 표기 | 현재 날짜와 검증 기준일 명시 |
| 보안 누락 | 민감정보, 과도한 권한, tool side effect 미표시 | 보안 체크리스트와 owner review |
| 드리프트 | 실제 코드와 문서 명령이 다름 | CI에서 명령/경로/스키마 검증 |
검증 체크리스트
사람 검증
| 항목 | 확인 |
|---|---|
| 근거 소스가 명시되어 있는가 | ☐ |
| 사실이 코드/스펙/공식 문서와 일치하는가 | ☐ |
| 프로젝트 고유 맥락이 반영되었는가 | ☐ |
| 추정과 확인된 사실이 분리되어 있는가 | ☐ |
| 민감 정보와 과도한 권한이 포함되지 않았는가 | ☐ |
| 소유자가 freshness 기준을 승인했는가 | ☐ |
자동 검증
| 항목 | 자동화 가능 |
|---|---|
| frontmatter 존재 여부 | 예 |
| 내부 링크 유효성 | 예 |
| 외부 링크 유효성 | 예, 주기적 cron 권장 |
| 코드 블록 문법 | 예 |
| OpenAPI schema/diff | 예 |
| 명령어와 package scripts 일치 | 예 |
| 에이전트 지침 준수 | 반자동 smoke test |