기술 문서 작성

기술 문서

목적

사람과 에이전트 모두를 위해 명확하고 실행 가능하며 유지보수 가능한 기술 문서를 작성하고 검토합니다. 여기에는 기여자 거버넌스 파일과 에이전트 명령 파일도 포함됩니다.

사용 시기

• 기존 제품/코드베이스(브라운필드)에서 문서를 만들거나 전면 개편할 때.
• 시간이 지나도 정확하고 재사용 가능한 에버그린 문서를 구축할 때.
• 문서 diff의 구조, 명확성, 운영 정확성을 검토할 때.
• 저장소 전체 문서 감사를 수행할 때(거버넌스 파일과 제품 문서 표면(docs/, README*, .md/.mdx/.mdc, Fern/Sphinx/Mintlify 스타일 소스) 모두 포함).
• AGENTS.md 및/또는 CONTRIBUTING.md를 업데이트하거나 검토하여 에이전트와 기여자 워크플로를 현재 저장소 관행에 맞출 때.
• 저장소 온보딩/문서를 개선할 때(기여 지침, 이슈 템플릿, PR 흐름, 검토 게이트 포함).
• alias 명령 파일(예: CLAUDE.md, AGENT.md, .cursorrules, .cursor/rules/*, .agent/, .agents/, .pi/)이 있는 저장소의 거버넌스 문서 전략을 설계할 때. AGENTS.md가 있을 경우 이를 표준으로 간주하고 alias는 호환성 인터페이스로 유지합니다.
• 누락된 파일, 깨진 명령, 정책 충돌을 발견하기 위해 반복적인 프롬프트가 필요했던 에이전트 파일 드리프트를 진단할 때.
• OpenClaw 페이지 유형, 문서 IA, 보존 및 검증 규칙 등 저장소별 문서 오버레이를 적용할 때.

워크플로

1. 작업 분류: build 또는 review; 컨텍스트: brownfield 또는 evergreen.
2. 요청된 파일, 디렉터리 또는 diff 범위를 초기에 인벤토리합니다. 문서 전체 작업의 경우 거버넌스 문서와 제품 문서를 모두 포함합니다. 저장소 크기만으로 범위가 지정된 검토가 확장되지는 않습니다.
3. 다국어 범위(여러 언어의 README/문서)를 감지하고 요구되는 동등성 수준을 정의합니다.
4. references/agent-and-contributing.md(에이전트 명령)와 CONTRIBUTING.md 워크플로 규칙(인벤토리, 표준/alias 매핑, 이중 모드 균형, 전달 기준, 우선순위/충돌 처리)을 읽습니다.
5. references/principles.md(Matt Palmer & OpenAI 규칙 집합)를 읽습니다.
6. OpenClaw 문서 작업의 경우, 빌드/검토 플레이북 전에 references/openclaw.md를 읽습니다.
7. 빌드 작업의 경우 references/build.md를 따릅니다.
8. 검토 작업의 경우 references/review.md를 따르고, 반복적인 프롬프트를 기다리지 않고 적극적으로 문제를 감지합니다.
9. 복잡하거나 고위험 작업(빌드 또는 검토)의 경우, 필요할 때 더 길고 깊으며 철저한 조사를 수행해도 괜찮습니다.
10. 가능한 경우 하위 에이전트를 사용하여 병렬 탐색/검토 작업을 수행한 후, 결과를 하나의 일관된 최종 결과물로 통합합니다.
11. 플랫폼/도구 선택이 권장 사항에 영향을 미칠 때 references/tooling.md를 사용합니다.
12. 요청된 범위 내에서 사전 문제 스윕을 실행합니다. 보고서 전용 모드가 요청되지 않은 경우 동일한 패스에서 높은 신뢰도의 결함을 수정합니다.
13. 브라운필드 모드에서는 현재 문서 IA, 도구, 릴리스 상태와의 호환성을 우선시합니다.
14. 에버그린 모드에서는 시대에 뒤처지지 않는 표현, 업데이트 전략, 내구성 있는 구조를 우선시합니다.
15. 전달 결과물과 함께 검증 노트, 동등성 상태, 남은 격차를 반환합니다.

하위 에이전트 오케스트레이션 지침

저장소가 크거나 요청된 변경 세트가 광범위할 때 하위 에이전트를 선호하며, 저장소 전체, 다중 프레임워크 또는 높은 충돌 작업에는 기본적으로 사용합니다.

• inventory-agent -> agents/inventory-agent.md (fast / Claude haiku): 파일/설정 검색, 커버리지 맵, 누락된 경로 확인.
• governance-agent -> agents/governance-agent.md (thinking / Claude sonnet): AGENTS/CONTRIBUTING/alias 우선순위, 충돌, 정책 드리프트.
• docs-framework-agent -> agents/docs-framework-agent.md (thinking / Claude sonnet): 프레임워크 설정, 상대 경로 기준, 파일 경로 대 URL 경로 매핑 확인.
• synthesis-agent -> agents/synthesis-agent.md (long / Claude opus): 하위 에이전트 출력을 하나의 우선순위화된 수정 계획과 통합 우선순위 모델로 병합.

입력

• 문서 유형(튜토리얼, 방법, 참조, 설명) 및 대상 독자.
• 파일 범위 또는 diff 범위.
• 문서 프레임워크/도구 제약 조건(Fern, Mintlify, Sphinx 등).
• 빌드/검토 모드 및 브라운필드/에버그린 의도.
• 대상 에이전트 및 사람 호환성 의도.
• 범위 내 문서 프레임워크 표면(예: Fern, Sphinx, Mintlify, Markdown/MDX/MDC/RST/RSC 파일).
• 원하는 조사 깊이/시간 예산(간략한 패스 vs 철저한 검토).
• 실행 모드(single-agent 또는 가능한 경우 sub-agent-assisted).
• 수정 모드(기본값 apply-fixes, 요청 시 report-only).
• 다국어 범위: 진실 공급원 언어, 대상 로케일, 동등성 기대치.
• 저장소별 오버레이 제약 조건(있는 경우).

출력

• 명확한 다음 단계가 포함된 업데이트된 초안 또는 검토 결과.
• 검증 노트(확인된 내용, 남은 내용).
• 장기적인 품질을 위한 탐색/유지보수 권장 사항.
• AGENTS/CONTRIBUTING이 수정된 경우 거버넌스 문서 정렬 요약.
• 에이전트 명령 표면 맵(기본 파일, alias 파일, Codex/Claude/Cursor 처리 계획).
• 문서 표면 커버리지 맵(/docs 아래 검토된 내용, README 계층 구조, 프레임워크별 소스 트리).
• 자동 감지된 이슈 목록 및 적용된 수정 사항(또는 명시적 보고서 전용 결과).
• 하위 에이전트가 사용된 경우 위임 노트(위임된 범위 및 결과 병합 방법).
• 다국어 동등성 노트(일치, 부분 일치(이유 포함), 또는 의도적으로 다름).
• 저장소별 오버레이가 사용된 경우 관련 노트.