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_name

project_type

data-science

license_type

proprietary

team_size

solo

project_type 옵션

data-science

backend-fastapi

cli-application

library-package

hypermodern-python

general-python

실행 프로세스

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: 사전 검증

# 현재 디렉토리 확인
ls -la

# 기존 파일 존재 시 경고

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 포함:

# {project_name} 프로젝트

## 빠른 명령어

| 명령어 | 설명 |
|--------|------|
| `uv sync` | 의존성 설치 |
| `pytest tests/ -v` | 테스트 실행 |
| `ruff check .` | 린트 검사 |
<프로젝트 타입별 추가 명령어>

## 참조 문서

- 전역 설정: `~/.claude/CLAUDE.md`
- Level 2: `@.claude/docs/conventions/`
- Level 3: `@.claude/docs/troubleshooting/`

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

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

{
  "permissions": {"mode": "delegate"},
  "hooks": {
    "on_context_complete": {"enabled": true},
    "on_nth_message": {"enabled": true, "n": 50}
  }
}

커스텀 커맨드 (

.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

[project]
name = "{project_name}"
version = "0.1.0"
requires-python = ">=3.12"
authors = [{name = "{git_name}", email = "{git_email}"}]
dependencies = []

[project.optional-dependencies]
dev = ["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/만
• 커스텀: 기본만 생성 후 수동 편집

# Claude
.claude/CLAUDE.local.md
.claude/settings.local.json

# Python
__pycache__/
.venv/
.pytest_cache/
.mypy_cache/

# IDE
.vscode/
.idea/

Step 11: README.md 생성

/manage-readme

Step 12: Git 초기화 (선택)

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

git init
git add .
git commit -m "chore: Initial project scaffolding"

사용 예시

예시 1: Data Science 프로젝트

/project-init transit-analysis data-science

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

예시 2: 대화형 입력

/project-init

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

예시 3: 커스텀 템플릿

/project-init my-project

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

계층적 메모리 사용법

Level 1 참조 (항상 로드)

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

Level 2 참조 (필요 시 로드)

@.claude/docs/conventions/python-style.md
@.claude/docs/conventions/testing.md

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

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

추적성 (Traceability)

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

def process_data(data: pd.DataFrame) -> pd.DataFrame:
    """데이터 전처리 수행.

    Traceability:
        - Upstream: REQ-001 (tasks/requirements.md#REQ-001)
        - Downstream: tests/test_process.py::test_process_data
    """
    ...

관련 스킬

주의사항

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에 포함됨