기술 문서 작성(Technical Documentation Authoring)
기술 문서를 안정적이고 유지보수 가능하며 탐색하기 쉬운 지식 매체로 컴파일합니다. 먼저 사실이 속한 위치와 독자가 필요한 것을 결정한 다음, 내용을 조직하고 마지막으로 표현을 다듬습니다.
핵심 원칙(Core principles)
- 작성 전에 정보 유형을 식별하세요. 발견 과정을 곧바로 문서 구조로 만들지 마십시오.
- 각 지속적인 사실은 단 하나의 표준 소유자(canonical owner)를 가집니다. 소유자는 소스 코드, 설정, 스키마, 생성기, 문서 또는 결정 기록일 수 있습니다.
- 파일 이름이나 기존 자료가 아니라 독자의 의도(reader intent)에 따라 문서 유형을 선택하세요.
- 글을 쓰기 전에 문서 계약(Document Contract)을 수립하세요: 독자, 목표, 주제, 범위, 제외 사항, 권위 있는 출처, 세부 수준 상한선.
- 문서 유형은 범위(scope)를 확장할 수 없습니다. 상위 문서는 직접 하위 항목을 요약하고 세부 사항 소유자에 대한 링크를 제공합니다.
- 조사, 구현 또는 커밋 순서가 아니라 전제 조건, 종속성 및 검증 가능한 결과에 따라 내용을 구성하세요.
- 현재 상태, 설계 이유 및 이력 서사는 각각 다른 문서의 책임으로 배치하세요.
- 경계를 넘을 때는 권위 있는 세부 사항에 링크하고, 현재 범위에 맞고 충분히 안정적인 내용만 유지하세요.
- 주 에이전트가 authoring plan을 동결한 후에만 하위 에이전트에 작업을 할당할지 결정하세요. 하위 에이전트는 경계가 명확한 부분적인 작성 작업만 수행합니다.
작업 계약(Working contract)
작성, 재작성, 분할, 병합 또는 구조 검토를 실행하기 전에 간단한 문서 계약(Document Contract)을 먼저 작성하세요. 내부적으로 완료할 수 있으며, 작업 정렬이 필요한 경우에만 이를 가시적인 결과물로 만듭니다.
다음 필드를 기록하세요:
- Reader intent(독자 의도): 독자가 학습, 작업 완료, 질의, 이해, 추적 또는 규칙 준수를 원하는지.
- Document type(문서 유형): 의도와 일치하는 주요 문서 유형. 하나의 문서는 하나의 주요 의도만 유지합니다.
- Subject(주제): 문서가 직접 담당하는 주제 또는 시스템 계층.
- Scope(범위): 포함되는 객체, 동작 및 깊이.
- Exclusions(제외 사항): 명시적으로 다른 문서나 권위 있는 출처에 맡겨진 내용.
- Authorities(권위 출처): 현재 사실을 뒷받침하는 소스 코드, 설정, 생성 파일, 결정 기록 또는 기존 문서.
- Detail ceiling(세부 수준 상한선): 현재 주제와 독자 목표 하에 허용되는 최고 세부 수준.
소유자, 독자 의도, 범위 또는 권위 출처를 확인할 수 없으면 불확실성을 그대로 두고 그 격차를 보고하세요. 경험에 의존하여 제품 결정이나 현재 동작을 임의로 보충하지 마십시오.
작성 워크플로우(Authoring workflow)
1. 작업 및 문서 위치 파악
새로 작성, 업데이트, 분할, 병합 또는 구조 검토 중 어떤 작업인지 식별하세요. 적용 가능한 AGENTS.md, CLAUDE.md, CONTEXT.md, 문서 인덱스 및 인접 문서를 읽어 저장소의 기존 계층 구조, 명명 규칙 및 링크 규칙을 확인합니다.
대상 문서가 존재하지 않으면 작업을 그린필드 문서화(greenfield documentation)로 간주합니다: 코드 디렉터리, 공개 API, 설정 스키마, 테스트, 예제, 명령어 및 생성 파일에서 후보 문서 맵을 구축합니다. 먼저 하나의 진입 문서가 필요한지, 아니면 소유자와 독자 의도에 따라 여러 문서로 나누어야 하는지 판단하세요. 전체 코드 프레임워크를 하나의 거대하고 포괄적인 설명으로 압축하지 마십시오.
완료 조건: 기존 문서가 있는 경우 대상 경로, 상위 문서, 직접 하위 문서 및 적용 가능한 로컬 규칙을 알고 있습니다. 기존 문서가 없는 경우 코드 프레임워크의 주요 경계, 후보 문서 집합, 각 문서의 초기 소유자 및 권위 출처를 알고 있습니다.
2. 정보 목록화 및 분류
보존할 사실, 설명, 단계, 예제, 제한 사항 및 이력 자료를 목록화하세요. 정보 유형별로 분류하고 현재 상태, 지속적인 이유, 운영 절차, 질의 자료, 규칙, 사고 및 생성된 내용을 구분하세요.
자세한 분류표가 필요한 경우 references/information-and-ownership.md를 읽으세요.
완료 조건: 각 후보 콘텐츠에는 정보 유형이 있습니다. 서로 다른 유형의 자료가 정의되지 않은 하나의 단락에 혼합되지 않습니다.
3. 사실을 표준 소유자(canonical owner)로 라우팅
각 지속적인 사실에 대해 기존 소유자를 찾으세요. 소스 코드, 설정, 스키마, 생성기 및 기존 결정 기록을 우선적으로 권위 출처로 사용합니다. 문서는 그 책임 범위 내의 설명, 프로세스 또는 안정적인 계약만 소유합니다.
이미 소유자가 있는 콘텐츠는 필수 요약과 소유자에 대한 링크만 유지합니다. 여러 충돌하는 소유자를 발견하면 충돌을 먼저 보고하고 해결해야 할 권위 문제를 기록하세요.
완료 조건: 각 중요 사실에는 단 하나의 소유자가 있습니다. 현재 문서는 다른 곳의 권위 있는 세부 사항을 복제하지 않습니다.
4. 독자 의도(reader intent)에 따라 문서 유형 선택
독자 목표에서 Tutorial, How-to, Reference, Explanation, ADR, Policy 또는 Postmortem과 같은 유형을 선택하세요. 하나의 파일에 여러 유형의 내용이 포함되어 있다고 해서 여러 주요 유형을 중복해서 부여하지 마십시오. 혼합된 의도가 탐색이나 유지보수에 영향을 미칠 정도가 되면 문서를 분할하세요.
유형 선택 및 구조 패턴에 대한 자세한 내용은 references/document-types-and-composition.md를 읽으세요.
완료 조건: "누가 왜 이 문서를 읽는가"를 한 문장으로 설명할 수 있고, 하나의 주요 문서 유형을 지목할 수 있습니다.
5. 범위(scope)와 세부 수준 상한선(detail ceiling) 고정
주제, 대상 독자, 목표, 포함 항목, 제외 항목, 권위 출처 및 세부 수준 상한선을 작성하세요. 문서를 자체 주제, 계층 수준 및 직접 하위 항목의 책임으로 제한하세요. 더 낮은 수준의 메커니즘, 테스트, 체크리스트 및 구현 세부 사항은 소유자로 이동시킵니다.
문서 유형은 범위를 확장할 수 없습니다. 상위 문서는 구성, 책임 및 상위 수준 동작을 설명합니다. 하위 문서는 유형 정의, 매개변수, 테스트 메커니즘 또는 구체적인 작업을 소유합니다.
완료 조건: 각 섹션은 "이것이 현재 독자 목표와 범위에 어떻게 기여하는가"에 답할 수 있습니다. 경계를 벗어난 자료는 이미 이동할 곳이나 링크가 있습니다.
6. 실행 가능한 작성 계획(Authoring Plan) 수립
먼저 독자가 알아야 할 전제 개념을 배치한 다음, 이에 의존하는 작업, 설명 또는 질의 콘텐츠를 배치하세요. 문서 유형에 해당하는 구조를 사용하고, 조사, 구현, 논의 또는 커밋 순서를 교육 순서로 사용하지 마십시오.
대규모 문서의 경우 섹션 트리, 사실 소유자, 섹션 종속성, 대상 파일, 제외 사항 및 각 섹션의 승인 조건을 기록하세요. 계획은 다른 에이전트가 전체 구조를 재설계하지 않고도 로컬 작업을 완료할 수 있도록 해야 합니다.
완료 조건: 독자가 후반부를 참조하지 않고도 필요한 용어, 전제 조건 또는 동작을 이해할 수 있어야 합니다. 각 주요 단락은 명확한 질문에 답변합니다. 각 계획 단위에는 고유한 범위와 완료 조건이 있습니다.
7. 실행 모드 선택 및 하위 에이전트 할당
기본적으로 단일 에이전트 경로를 사용합니다. 다음 조건이 모두 충족되는 경우에만 하위 에이전트를 시작하세요:
- 계획이 이미 동결되었고, 독자 의도, 문서 유형, 범위, 소유자 및 주요 구조에 해결되지 않은 충돌이 없습니다.
- 독립적으로 읽고, 쓰고, 검증할 수 있는 작업 단위가 최소 두 개 이상 존재합니다.
- 각 작업 단위에는 고유한 대상 파일 또는 섹션 소유자가 있으며, 작업 간에 동일한 본문 텍스트를 동시에 편집하지 않습니다.
- 종속성이 명시적으로 기록되었습니다. 공유해야 할 사실에는 하위 에이전트가 서로 추측하는 데 의존하지 않고 권위 있는 출처가 있습니다.
- 할당 및 병합 비용이 주 에이전트가 전체 문서 컨텍스트를 지속적으로 유지하는 비용보다 낮습니다.
조건이 충족되면 references/orchestration-and-delegation.md를 읽고, 주 에이전트가 할당 브리핑을 생성하여 하위 에이전트를 호출합니다. 주 에이전트는 글로벌 계획, 사실 귀속, 교차 섹션 링크, 병합 결정 및 최종 승인 권한을 유지합니다. 하위 에이전트는 문서 유형을 재설계하지 않고, 다른 작업 단위를 수정하지 않으며, 입증되지 않은 사실을 결론으로 제시하지 않습니다.
조건이 충족되지 않으면 주 에이전트가 단독으로 작성을 계속합니다. 단일 파일의 부분 보완, 소량의 단락 수정, 단일 소유자의 Reference 업데이트 및 강력한 직렬 종속성은 모두 단일 에이전트 경로에 속합니다.
완료 조건: 단일 에이전트(single-agent) 또는 위임 실행(delegated execution)이 명확하게 선택되었습니다. 위임된 경우 모든 작업에는 경계, 종속성, 출력 형식 및 승인 조건이 있습니다.
8. 현재 계약 및 관찰 가능한 동작 직접 작성
구체적인 주체, 동작, API, 옵션 및 결과로 내용을 표현하세요. 먼저 현재 상태와 독자가 관찰할 수 있는 동작을 작성한 다음, 기본값, 제한 사항, 예외, 원리 및 트레이드오프를 추가하세요. "반드시", "기본", "권장", "할 수 있음"을 명확히 구분하세요.
Tutorial 및 How-to는 최소 예제를 설명 중심으로 할 수 있습니다. Reference는 검색 가능한 정의와 경계를 중심으로 합니다. ADR 및 Postmortem은 각각 필요한 이유나 타임라인을 유지합니다.
전체 표현 규칙 및 검증 체크리스트가 필요한 경우 references/writing-and-validation.md를 읽으세요.
완료 조건: 본문은 유지보수 가능한 사실, 계약 또는 단계를 진술하며, 추론 과정, 구현 로그 또는 공허한 메타 발언이 아닙니다. 위임된 작업의 출력은 모두 주 에이전트에 회수되었습니다.
9. 병합 및 통일
하위 에이전트를 사용한 경우 주 에이전트는 각 출력이 작성 계획(authoring plan)에 부합하는지 항목별로 확인합니다. 중복 사실, 용어 변이, 섹션 경계, 교차 링크 및 스타일 불일치를 해결합니다. 해결되지 않은 문제는 중앙에 기록하고, 로컬 에이전트가 글로벌 결정을 임의로 내리지 못하게 합니다. 하위 에이전트의 과정 설명을 본문에 직접 통합하지 말고, 유지보수 가능한 결과만 병합합니다.
완료 조건: 각 할당 단위에는 결과물 또는 명확한 차단 이유가 있습니다. 동일한 사실에 대해 여러 소유자가 없습니다. 글로벌 목차, 링크, 용어 및 독자 경로가 일관됩니다.
10. 링크, 축소 및 검증
중복 사실, 수동 복사 목록, 관련 없는 배경 및 세부 수준 상한선을 초과하는 세부 사항을 제거하세요. 목표를 설명하는 링크로 소유자, 하위 문서, 소스 코드 및 결정 기록을 연결합니다. 참조 파일의 순서에 따라 구조적 및 언어적 검증을 완료하세요.
완료 조건: 소유자, 유형, 범위, 종속성 순서, 현재/이력 경계, 링크 및 표현 규칙이 모두 확인되었습니다. 처리되지 않은 충돌이나 불확실성이 남아 있지 않습니다.
경계(Boundaries)
저장소 고유의 파일 계층 구조, 스크립트 명령어, 단어 수 예산, 코드 블록 컴파일 규칙, 이중 언어 프로세스 또는 특정 용어를 일반 규칙으로 작성하지 마세요. 로컬 프로젝트 규칙을 읽고 따르십시오. 이 스킬은 프로젝트 간 안정적인 문서 결정 프레임워크만 제공합니다.
README, architecture.md 또는 AGENTS.md를 고정된 일반 문서 유형으로 간주하지 마세요. 먼저 독자 의도를 판단한 다음, 해당 캐리어에 대한 프로젝트의 구체적인 규칙을 따르세요.
최종 인계(Final handoff)
완료 후 간략히 설명: 문서 유형 및 독자 의도, 표준 소유자(canonical owner) 처리, 범위 경계, 관련 링크 또는 분할, 그리고 여전히 사람이 결정해야 할 사실 충돌. 해결되지 않은 문제를 현재 상태로 위장하지 마십시오.