project-init

Python 프로젝트 초기화 및 문서화 자동화 스킬

목적

1. 프로젝트 기반 구축: 폴더 구조, 설정 파일, 문서 자동 생성
2. 계층적 메모리 구조: Level 1-3 문서 계층으로 컨텍스트 효율화
3. 추적성 (Traceability): 코드와 요구사항의 명확한 연결
4. 일관된 프로젝트 구조: 베스트 프랙티스 적용

핵심 개념

계층적 메모리 (Aidoc Framework 기반):

• Level 1 (Core): 항상 로드 - CLAUDE.md, Quick Commands
• Level 2 (Detailed): 필요 시 로드 - Conventions, Workflows
• Level 3 (Reference): 명시적 참조 - Troubleshooting, ADR

추적성: 모든 코드는 요구사항과 명시적으로 연결

스킬 유형

Composite Skill - 다음 스킬들을 순차 조합:

파라미터

project_type 옵션

실행 프로세스

Step 1: 초기화 방식 선택

AskUserQuestion으로 표준 타입 또는 커스텀 템플릿 중 선택한다.

• 표준 타입: project_type 파라미터 기반으로 자동 생성
• 커스텀 템플릿: _custom-template.md 기반으로 폴더별 선택

Step 2: 파라미터 수집

파라미터 미제공 시 AskUserQuestion으로 대화형 입력:

1. project_name (필수)
2. project_type 또는 커스텀 폴더 선택
3. license_type (proprietary/MIT/Apache-2.0)
4. team_size (solo/small/medium/large)
5. Git 작성자 정보 (Git config에서 자동 추출 가능)

Step 3: 사전 검증

bash
1# 현재 디렉토리 확인
2ls -la
3
4# 기존 파일 존재 시 경고

Step 4: 디렉토리 구조 생성

/scaffold-structure를 호출하여 프로젝트 타입에 맞는 폴더 생성:

project-root/
├── .claude/
│   ├── CLAUDE.md               # Level 1: 핵심 컨텍스트
│   ├── settings.json
│   ├── commands/               # 커스텀 커맨드 (5개)
│   └── docs/                   # Level 2, 3 문서
├── src/{project_name}/
├── tests/
├── docs/
├── pyproject.toml
├── README.md
└── .gitignore

프로젝트 타입별 추가 폴더:

• data-science: data/, notebooks/, models/
• backend-fastapi: src/api/, src/core/, src/models/, docker/
• cli-application: src/cli/commands/

Step 5: LICENSE 파일 생성

/license-guide {license_type} 호출하여 라이센스 파일 생성

Step 6: CLAUDE.md 생성 (Level 1)

프로젝트 타입에 맞는 Quick Commands 포함:

markdown
1# {project_name} 프로젝트
2
3## 빠른 명령어
4
5| 명령어 | 설명 |
6|--------|------|
7| `uv sync` | 의존성 설치 |
8| `pytest tests/ -v` | 테스트 실행 |
9| `ruff check .` | 린트 검사 |
10<프로젝트 타입별 추가 명령어>
11
12## 참조 문서
13
14- 전역 설정: `~/.claude/CLAUDE.md`
15- Level 2: `@.claude/docs/conventions/`
16- Level 3: `@.claude/docs/troubleshooting/`

템플릿 상세: [@templates/skill-examples/project-init/claude-md-template.md]

Step 7: settings.json 및 커스텀 커맨드 생성

json
1{
2  "permissions": {"mode": "delegate"},
3  "hooks": {
4    "on_context_complete": {"enabled": true},
5    "on_nth_message": {"enabled": true, "n": 50}
6  }
7}

커스텀 커맨드 (.claude/commands/):

• /compact: 컨텍스트 압축
• /sync-diagrams: 다이어그램 동기화
• /recommend-memory: CLAUDE.md 업데이트 추천
• /cleanup-memory: CLAUDE.md 정리
• /update-docs: 문서 일괄 업데이트

Step 8: Level 2, 3 문서 템플릿 생성

.claude/docs/ 구조:

• conventions/: python-style.md, testing.md, documentation.md
• workflows/: development.md, deployment.md, review.md
• references/: architecture.md
• troubleshooting/: guide.md
• decisions/: adr-template.md

Step 9: pyproject.toml 생성

/setup-uv-env init 호출하여 uv 환경 초기화:

toml
1[project]
2name = "{project_name}"
3version = "0.1.0"
4requires-python = ">=3.12"
5authors = [{name = "{git_name}", email = "{git_email}"}]
6dependencies = []
7
8[project.optional-dependencies]
9dev = ["pytest>=8.0", "ruff>=0.3", "mypy>=1.8"]

authors 필드: Git config에서 자동 추출 또는 수동 입력

프로젝트 타입별 의존성: [@templates/skill-examples/project-init/dependencies-by-type.md]

Step 10: .gitignore 생성

AskUserQuestion으로 구성 방식 선택:

• 표준 템플릿: Python + 프로젝트 타입별 패턴
• 최소: pycache/, .venv/만
• 커스텀: 기본만 생성 후 수동 편집

gitignore
1# Claude
2.claude/CLAUDE.local.md
3.claude/settings.local.json
4
5# Python
6__pycache__/
7.venv/
8.pytest_cache/
9.mypy_cache/
10
11# IDE
12.vscode/
13.idea/

Step 11: README.md 생성

/manage-readme 호출하여 프로젝트 타입에 맞는 README 생성

Step 12: Git 초기화 (선택)

AskUserQuestion으로 Git 초기화 여부 확인:

bash
1git init
2git add .
3git commit -m "chore: Initial project scaffolding"

사용 예시

예시 1: Data Science 프로젝트

bash
1/project-init transit-analysis data-science

자동으로 data/, notebooks/, models/ 폴더 및 data science 의존성 포함

예시 2: 대화형 입력

bash
1/project-init

프로젝트명, 타입, 라이센스, 팀 규모를 차례로 질문받음

예시 3: 커스텀 템플릿

bash
1/project-init my-project

초기화 방식 선택 → "커스텀 템플릿" → 폴더별 선택 (multiSelect)

계층적 메모리 사용법

Level 1 참조 (항상 로드)

markdown
1.claude/CLAUDE.md의 내용은 항상 컨텍스트에 포함됨

Level 2 참조 (필요 시 로드)

markdown
1@.claude/docs/conventions/python-style.md
2@.claude/docs/conventions/testing.md

Level 3 참조 (명시적 요청 시)

markdown
1@.claude/docs/troubleshooting/guide.md
2@.claude/docs/decisions/adr-template.md

추적성 (Traceability)

모든 코드는 요구사항과 연결되어야 한다:

python
1def process_data(data: pd.DataFrame) -> pd.DataFrame:
2    """데이터 전처리 수행.
3
4    Traceability:
5        - Upstream: REQ-001 (tasks/requirements.md#REQ-001)
6        - Downstream: tests/test_process.py::test_process_data
7    """
8    ...

관련 스킬

주의사항

1. 기존 파일 덮어쓰기 금지: 기존 파일 존재 시 경고 및 확인
2. Git 초기화 선택적: 사용자에게 Git 초기화 여부 질문
3. .claude/ 패턴*: .gitignore에 포함되어 있음. 팀 협업 시 필요한 파일은 git add -f로 명시적 추가

다음 단계

초기화 후:

1. TODO 플레이스홀더 설정: grep -r "\[TODO:" .claude/로 미설정 항목 확인
2. CLAUDE.md 작성: 프로젝트 개요, 기술 스택 완성
3. 개발 표준 수립: .claude/docs/conventions/ 검토
4. 첫 ADR 작성: 기술 스택 선정 근거 기록
5. 첫 기능 구현: /doc-prd → /doc-tasks → /3-step-workflow

참조 템플릿

• CLAUDE.md: [@templates/skill-examples/project-init/claude-md-template.md]
• README.md: [@templates/skill-examples/project-init/readme-template.md]
• Level 2 문서: [@templates/skill-examples/project-init/level2-docs-template.md]
• 의존성 상세: [@templates/skill-examples/project-init/dependencies-by-type.md]

참고 자료

• Aidoc Flow Framework: https://github.com/vladm3105/aidoc-flow-framework
• PyPA Packaging Guide: https://packaging.python.org/

Changelog

Gotchas (실패 포인트)

• pyproject.toml 없이 setup.py 사용 — 모던 Python 패키징 표준 미준수
• pre-commit install 누락 시 hook 미동작
• CLAUDE.md 없이 시작 시 Claude Code가 컨텍스트 파악 못함
• .gitignore에 .venv/ 누락 시 가상환경이 git에 포함됨