코드 문서화 스킬은(는) 무엇을 하나요?
개요
이 스킬은 소프트웨어 프로젝트, 코드베이스, 라이브러리 및 API에 대한 전문적이고 포괄적인 문서를 생성합니다. React, Django, Stripe, Kubernetes와 같은 프로젝트의 업계 모범 사례를 따라 정확하고 잘 구조화되어 신규 기여자와 숙련된 개발자 모두에게 유용한 문서를 제공합니다.
출력 범위는 단일 파일 README부터 여러 문서로 구성된 개발자 가이드까지이며, 항상 프로젝트의 복잡성과 사용자 요구에 맞춰집니다.
핵심 기능
- 배지, 설치, 사용법 및 API 참조가 포함된 포괄적인 README.md 파일 생성
- 소스 코드 분석을 통한 API 참조 문서 생성
- 다이어그램이 포함된 아키텍처 및 설계 문서 생성
- 개발자 온보딩 및 기여 가이드 작성
- 커밋 기록 또는 릴리스 노트를 기반으로 체인지로그 생성
- 언어별 규칙을 따르는 인라인 코드 문서 생성
- JSDoc, docstrings, GoDoc, Javadoc 및 Rustdoc 형식 지원
- 프로젝트 언어 및 생태계에 맞춰 문서 스타일 조정
이 스킬을 사용해야 하는 경우
다음과 같은 경우 항상 이 스킬을 로드하십시오:
- 사용자가 모든 코드에 대해 "문서화", "문서 생성" 또는 "문서 작성"을 요청하는 경우
- 사용자가 README, API 참조 또는 개발자 가이드를 요청하는 경우
- 사용자가 코드베이스나 저장소를 공유하고 문서 생성을 원하는 경우
- 사용자가 기존 문서 개선 또는 업데이트를 요청하는 경우
- 사용자가 다이어그램을 포함한 아키텍처 문서가 필요한 경우
- 사용자가 체인지로그 또는 마이그레이션 가이드를 요청하는 경우
문서화 워크플로우
1단계: 코드베이스 분석
문서를 작성하기 전에 코드베이스를 완전히 이해합니다.
1.1단계: 프로젝트 탐색
프로젝트 기본 사항을 식별합니다:
| 필드 | 확인 방법 |
|---|---|
| 언어 | 파일 확장자, package.json, pyproject.toml, go.mod, Cargo.toml 등 확인 |
| 프레임워크 | 알려진 프레임워크(React, Django, Express, Spring 등)에 대한 종속성 확인 |
| 빌드 시스템 | Makefile, CMakeLists.txt, webpack.config.js, build.gradle 등 확인 |
| 패키지 관리자 | npm/yarn/pnpm, pip/uv/poetry, cargo, go modules 등 |
| 프로젝트 구조 | 디렉터리 트리를 매핑하여 아키텍처 이해 |
| 진입점 | 메인 파일, CLI 진입점, 내보낸 모듈 찾기 |
| 기존 문서 | 기존 README, docs/, wiki 또는 인라인 문서 확인 |
1.2단계: 코드 구조 분석
샌드박스 도구를 사용하여 코드베이스를 탐색합니다:
# 디렉터리 구조 가져오기
ls /mnt/user-data/uploads/project-dir/
# 주요 파일 읽기
read_file /mnt/user-data/uploads/project-dir/package.json
read_file /mnt/user-data/uploads/project-dir/pyproject.toml
# 공개 API 표면 검색
grep -r "export " /mnt/user-data/uploads/project-dir/src/
grep -r "def " /mnt/user-data/uploads/project-dir/src/ --include="*.py"
grep -r "func " /mnt/user-data/uploads/project-dir/ --include="*.go"
1.3단계: 문서화 범위 식별
분석을 기반으로 생성할 문서를 결정합니다:
| 프로젝트 크기 | 권장 문서 |
|---|---|
| 단일 파일 / 스크립트 | 인라인 주석 + 사용법 헤더 |
| 소형 라이브러리 | API 참조가 포함된 README |
| 중형 프로젝트 | README + API 문서 + 예제 |
| 대형 프로젝트 | README + 아키텍처 + API + 기여 + 체인지로그 |
2단계: 문서 생성
2.1단계: README 생성
모든 프로젝트에는 README가 필요합니다. 다음 구조를 따릅니다:
# 프로젝트 이름
[한 줄 프로젝트 설명 — 무엇을 하고 왜 중요한지]
[](#) [](#)
## 기능
- [주요 기능 1 — 간단한 설명]
- [주요 기능 2 — 간단한 설명]
- [주요 기능 3 — 간단한 설명]
## 빠른 시작
### 사전 요구 사항
- [버전 요구 사항이 있는 사전 요구 사항 1]
- [버전 요구 사항이 있는 사전 요구 사항 2]
### 설치
[복사하여 붙여넣을 수 있는 코드 블록이 포함된 설치 명령어]
### 기본 사용법
[핵심 기능을 보여주는 최소한의 작동 예제]
## 문서
- [별도인 경우 전체 API 참조 링크]
- [별도인 경우 아키텍처 문서 링크]
- [해당하는 경우 예제 디렉터리 링크]
## API 참조
[소규모 프로젝트용 인라인 API 참조 또는 생성된 문서 링크]
## 구성
[환경 변수, 구성 파일 또는 런타임 옵션]
## 예제
[일반적인 사용 사례를 다루는 2-3개의 실제 예제]
## 개발
### 설정
[개발 환경 설정 방법]
### 테스트
[테스트 실행 방법]
### 빌드
[프로젝트 빌드 방법]
## 기여
[기여 지침 또는 CONTRIBUTING.md 링크]
## 라이선스
[라이선스 정보]
2.2단계: API 참조 생성
각 공개 API 표면에 대해 다음을 문서화합니다:
함수 / 메서드 문서:
### `functionName(param1, param2, options?)`
이 함수가 수행하는 작업에 대한 간략한 설명.
**매개변수:**
| 매개변수 | 유형 | 필수 | 기본값 | 설명 |
|-----------|------|----------|---------|-------------|
| `param1` | `string` | 예 | — | param1 설명 |
| `param2` | `number` | 예 | — | param2 설명 |
| `options` | `Object` | 아니요 | `{}` | 구성 옵션 |
| `options.timeout` | `number` | 아니요 | `5000` | 밀리초 단위 제한 시간 |
**반환값:** `Promise<Result>` — 반환값 설명
**발생 오류:**
- `ValidationError` — param1이 비어 있는 경우
- `TimeoutError` — 작업이 제한 시간을 초과한 경우
**예제:**
javascript
const result = await functionName("hello", 42, { timeout: 10000 });
console.log(result.data);
클래스 문서:
### `ClassName`
클래스와 그 목적에 대한 간략한 설명.
**생성자:**
javascript
new ClassName(config)
| 매개변수 | 유형 | 설명 |
|-----------|------|-------------|
| `config.option1` | `string` | 설명 |
| `config.option2` | `boolean` | 설명 |
**메서드:**
- [`method1()`](#method1) — 간략한 설명
- [`method2(param)`](#method2) — 간략한 설명
**속성:**
| 속성 | 유형 | 설명 |
|----------|------|-------------|
| `property1` | `string` | 설명 |
| `property2` | `number` | 읽기 전용. 설명 |
2.3단계: 아키텍처 문서
중대형 프로젝트의 경우 아키텍처 문서를 포함합니다:
# 아키텍처 개요
## 시스템 다이어그램
[상위 수준 아키텍처를 보여주는 Mermaid 다이어그램 포함]
mmermaid
graph TD
A[클라이언트] --> B[API 게이트웨이]
B --> C[서비스 A]
B --> D[서비스 B]
C --> E[(데이터베이스)]
D --> E
## 구성 요소 개요
### 구성 요소 이름
- **목적**: 이 구성 요소가 수행하는 작업
- **위치**: `src/components/name/`
- **종속성**: 의존하는 대상
- **공개 API**: 주요 내보내기 또는 인터페이스
## 데이터 흐름
[주요 작업에 대한 시스템 내 데이터 흐름 설명]
## 설계 결정
### 결정 제목
- **컨텍스트**: 이 결정에 이르게 된 상황
- **결정**: 결정된 사항
- **근거**: 이 접근 방식이 선택된 이유
- **절충점**: 희생된 사항
2.4단계: 인라인 코드 문서
언어에 적합한 인라인 문서를 생성합니다:
Python (Docstrings — Google 스타일):
def process_data(input_path: str, options: dict | None = None) -> ProcessResult:
"""지정된 파일 경로에서 데이터를 처리합니다.
입력 파일을 읽고 제공된 옵션에 따라 변환을 적용한 후
구조화된 결과 객체를 반환합니다.
Args:
input_path: 입력 데이터 파일의 절대 경로.
CSV, JSON 및 Parquet 형식을 지원합니다.
options: 선택적 구성 사전.
- "validate" (bool): 입력 유효성 검사를 활성화합니다. 기본값은 True입니다.
- "format" (str): 출력 형식("json" 또는 "csv"). 기본값은 "json"입니다.
Returns:
변환된 데이터와 메타데이터를 포함하는 ProcessResult입니다.
Raises:
FileNotFoundError: input_path가 존재하지 않는 경우.
ValidationError: 유효성 검사가 활성화되고 데이터가 잘못된 경우.
Example:
>>> result = process_data("/data/input.csv", {"validate": True})
>>> print(result.row_count)
1500
"""
TypeScript (JSDoc / TSDoc):
/**
* API에서 사용자 데이터를 가져와 표시용으로 변환합니다.
*
* @param userId - 사용자의 고유 식별자
* @param options - 가져오기 작업에 대한 구성 옵션
* @param options.includeProfile - 전체 프로필을 포함할지 여부. 기본값은 `false`입니다.
* @param options.cache - 캐시 기간(초). 비활성화하려면 `0`으로 설정합니다.
* @returns 렌더링할 준비가 된 변환된 사용자 데이터
* @throws {NotFoundError} 사용자 ID가 존재하지 않는 경우
* @throws {NetworkError} API에 연결할 수 없는 경우
*
* @example
* ```ts
* const user = await fetchUser("usr_123", { includeProfile: true });
* console.log(user.displayName);
* ```
*/
Go (GoDoc):
// ProcessData는 지정된 경로의 입력 파일을 읽고 지정된 변환을 적용한 후
// 처리된 결과를 반환합니다.
//
// 입력 경로는 CSV 또는 JSON 파일의 절대 경로여야 합니다.
// options가 nil이면 기본 옵션이 사용됩니다.
//
// ProcessData는 파일이 존재하지 않거나 구문 분석할 수 없는 경우 오류를 반환합니다.
func ProcessData(inputPath string, options *ProcessOptions) (*Result, error) {
3단계: 품질 보증
3.1단계: 문서 완전성 확인
문서가 다음을 포함하는지 확인합니다:
- 무엇인지 — 신규 사용자가 이해할 수 있는 명확한 프로젝트 설명
- 존재 이유 — 해결하는 문제와 가치 제안
- 설치 방법 — 복사하여 붙여넣을 수 있는 설치 명령어
- 사용 방법 — 최소한 하나의 작동 예제 포함
- API 표면 — 모든 공개 함수, 클래스 및 유형이 문서화됨
- 구성 — 모든 환경 변수, 구성 파일 및 옵션
- 오류 처리 — 일반적인 오류 및 해결 방법
- 기여 — 개발 환경 설정 및 변경 제출 방법
3.2단계: 품질 기준
| 기준 | 확인 |
|---|---|
| 정확성 | 모든 코드 예제가 설명된 API에서 실제로 작동해야 함 |
| 완전성 | 문서화되지 않은 공개 API 표면이 없어야 함 |
| 일관성 | 전체적으로 동일한 서식 및 구조 유지 |
| 최신성 | 문서가 이전 버전이 아닌 현재 코드와 일치해야 함 |
| 접근성 | 설명 없는 전문 용어가 없어야 하며, 약어는 첫 사용 시 정의되어야 함 |
| 예제 | 모든 복잡한 개념에 대해 최소한 하나의 실제 예제가 있어야 함 |
3.3단계: 상호 참조 검증
다음을 확인합니다:
- 언급된 모든 파일 경로가 프로젝트에 존재하는지
- 참조된 모든 함수와 클래스가 코드에 존재하는지
- 모든 코드 예제가 올바른 함수 시그니처를 사용하는지
- 버전 번호가 프로젝트의 실제 버전과 일치하는지
- 모든 링크(내부 및 외부)가 유효한지
문서 스타일 가이드
작성 원칙
- "이유"를 먼저 제시 — 작동 방식을 설명하기 전에 존재 이유를 설명합니다.
- 점진적 공개 — 간단하게 시작하고 점차 복잡성을 추가합니다.
- 보여주고 말하지 마세요 — 긴 설명보다 코드 예제를 선호합니다.
- 능동태 — "함수가 X를 반환합니다" ("X가 함수에 의해 반환됩니다"가 아님)
- 현재 시제 — "서버가 포트 8080에서 시작됩니다" ("서버가 포트 8080에서 시작될 것입니다"가 아님)
- 2인칭 — "사용자가 구성할 수 있습니다"가 아닌 "구성할 수 있습니다"
서식 규칙
- ATX 스타일 헤더 사용 (
#,##,###) - 언어 지정과 함께 펜스 코드 블록 사용 (
```python,```bash) - 구조화된 정보(매개변수, 옵션, 구성)에 테이블 사용
- 중요한 참고 사항, 경고 및 팁에 주의 표시 사용
- 줄 길이를 읽기 쉽게 유지(소스에서 산문을 약 80-100자로 줄 바꿈)
- 함수 이름, 파일 경로, 변수 이름 및 CLI 명령어에
코드 서식사용
언어별 규칙
| 언어 | 문서 형식 | 스타일 가이드 |
|---|---|---|
| Python | Google 스타일 docstrings | PEP 257 |
| TypeScript/JavaScript | TSDoc / JSDoc | TypeDoc 규칙 |
| Go | GoDoc 주석 | Effective Go |
| Rust | Rustdoc (///) | Rust API 지침 |
| Java | Javadoc | Oracle Javadoc 가이드 |
| C/C++ | Doxygen | Doxygen 매뉴얼 |
출력 처리
생성 후:
- 문서 파일을
/mnt/user-data/outputs/에 저장 - 여러 파일 문서의 경우 프로젝트 디렉터리 구조 유지
present_files도구를 사용하여 생성된 파일을 사용자에게 제시- 특정 섹션을 반복하거나 세부 수준을 조정하는 옵션 제공
- 유용할 수 있는 추가 문서 제안
참고 사항
- 문서를 작성하기 전에 항상 실제 코드를 분석하십시오. API 시그니처나 동작을 추측하지 마십시오.
- 기존 문서가 있는 경우, 사용자가 명시적으로 다시 쓰기를 요청하지 않는 한 그 구조를 유지하십시오.
- 대규모 코드베이스의 경우 공개 API 표면과 주요 추상화를 먼저 문서화하는 데 우선 순위를 두십시오.
- 문서는 프로젝트의 기존 문서와 동일한 언어로 작성되어야 하며, 기존 문서가 없는 경우 기본적으로 영어를 사용합니다.
- 체인지로그를 생성할 때는 Keep a Changelog 형식을 사용하십시오.
- 이 스킬은 타사 통합 또는 종속성을 문서화하기 위해
deep-research스킬과 함께 사용하면 효과적입니다.