Project Cleanup Skill

프로젝트 정리 작업을 수행합니다. SSDD 원칙에 따라 문서/스펙 업데이트, 테스트, 커밋을 자동화합니다.

트리거

•/project-cleanup 명령
•"프로젝트 정리", "커밋 준비", "작업 마무리" 프롬프트

실행 흐름

code

1단계: 변경사항 분석
    ↓
2단계: 문서/스펙 업데이트 (SSDD)
    ↓
3단계: Unit Test 실행
    ↓
4단계: 에러 수정
    ↓
5단계: Git Commit

실행 단계

1단계: 변경사항 분석

현재 작업 디렉토리의 변경사항을 분석합니다.

bash

# 변경된 파일 목록
git status

# 변경 내용 확인
git diff --stat
git diff

분석 항목:

•신규 파일 (Untracked)
•수정된 파일 (Modified)
•삭제된 파일 (Deleted)
•변경 유형 분류 (코드/문서/설정/테스트)

2단계: 문서/스펙 업데이트 (SSDD)

SSDD (Skillful Spec-Driven Development) 원칙에 따라 문서를 업데이트합니다.

업데이트 대상:

변경 유형	업데이트 문서	업데이트 내용
Agent 추가/수정	CLAUDE.md	Sub Agent 섹션
Skill 추가/수정	CLAUDE.md	Skills 섹션
API 추가/수정	docs/specs/api-spec.md	엔드포인트 명세
스키마 변경	data/schemas/*.cypher	Ontology 스키마
컴포넌트 추가	docs/specs/component-spec.md	UI 컴포넌트 명세

SSDD 체크리스트:

code

□ 명세와 구현 일치 확인
□ 버전 번호 업데이트 (필요시)
□ 마지막 업데이트 날짜 갱신
□ 변경 이력 기록
□ 관련 문서 링크 확인

자동 업데이트:

python

# CLAUDE.md 프로젝트 구조 동기화
sync_project_structure()

# 버전 업데이트 (변경 규모에 따라)
if breaking_change:
    bump_version("major")
elif new_feature:
    bump_version("minor")
else:
    bump_version("patch")

3단계: Unit Test 실행

변경된 부분에 대한 테스트를 실행합니다.

bash

# Python 테스트 (pytest)
pytest tests/ -v --tb=short

# 특정 모듈 테스트
pytest tests/test_agents.py -v

# 커버리지 확인
pytest --cov=backend --cov-report=term-missing

# TypeScript 테스트 (vitest/jest)
npm run test

# 타입 체크
mypy backend/
npm run type-check

테스트 범위:

변경 영역	테스트 대상
Agent	tests/test_agents.py
API	tests/test_api.py
Database	tests/test_database.py
Frontend	apps/web/*/.test.ts

4단계: 에러 수정

테스트 실패 시 에러를 수정합니다.

에러 처리 우선순위:

•Critical: 테스트 실패 → 즉시 수정
•High: 타입 에러 → 수정 필요
•Medium: 린트 경고 → 권장 수정
•Low: 스타일 이슈 → 선택적 수정

자동 수정 시도:

bash

# Python 린트 자동 수정
ruff check --fix .
ruff format .

# TypeScript/JavaScript 자동 수정
npm run lint:fix
npm run format

수동 수정 필요 시:

•에러 위치 및 내용 표시
•수정 제안 제공
•사용자 확인 요청

5단계: Git Commit

모든 검증 통과 후 커밋을 생성합니다.

bash

# 변경사항 스테이징
git add .

# 커밋 메시지 생성 (Conventional Commits)
git commit -m "$(cat <<'EOF'
<type>(<scope>): <description>

<body>

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
EOF
)"

커밋 메시지 규칙:

Type	설명	예시
feat	새로운 기능	feat(agent): query-decomposition 에이전트 추가
fix	버그 수정	fix(api): 인증 토큰 만료 처리
docs	문서 수정	docs: CLAUDE.md 프로젝트 구조 업데이트
refactor	리팩토링	refactor(db): 쿼리 최적화
test	테스트 추가	test(agent): validator 에이전트 테스트
chore	빌드/설정	chore: 의존성 업데이트

자동 판단 로직

커밋 가능 여부 판정

•
커밋 가능 (Green):
- •모든 테스트 통과
- •타입 체크 통과
- •린트 에러 없음
•
경고 후 커밋 (Yellow):
- •테스트 통과
- •린트 경고만 존재
- •사용자 확인 필요
•
커밋 불가 (Red):
- •테스트 실패
- •타입 에러 존재
- •수정 후 재시도 필요

변경 규모 판정

규모	조건	버전
Major	Breaking Changes, API 변경	X.0.0
Minor	새 기능 추가	0.X.0
Patch	버그 수정, 문서 수정	0.0.X

출력 예시

code

🔄 프로젝트 정리 시작...

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
📋 1. 변경사항 분석
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

신규 파일: 11개
  - .claude/agents/query-decomposition.md
  - .claude/agents/option-generator.md
  - .claude/agents/impact-simulator.md
  - .claude/agents/success-probability.md
  - .claude/agents/validator.md
  - .claude/agents/workflow-builder.md
  - .claude/skills/project-plan/SKILL.md
  - .claude/skills/capacity-forecast/SKILL.md
  - .claude/skills/go-nogo/SKILL.md
  - .claude/skills/headcount-analysis/SKILL.md
  - .claude/skills/competency-gap/SKILL.md

수정된 파일: 0개
삭제된 파일: 0개

변경 유형: Agent/Skill 추가 (Minor)

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
📝 2. 문서/스펙 업데이트 (SSDD)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

[✓] CLAUDE.md - Sub Agent 섹션 확인
[✓] CLAUDE.md - Skills 섹션 확인
[✓] 프로젝트 구조 동기화 완료
[✓] 버전: 0.1.0 → 0.2.0 (Minor)

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
🧪 3. Unit Test 실행
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

pytest tests/ -v
======================== test session starts ========================
collected 15 items

tests/test_agents.py::test_orchestrator PASSED
tests/test_agents.py::test_query_decomposition PASSED
...

======================== 15 passed in 2.34s =========================

mypy backend/
Success: no issues found in 12 source files

ruff check .
All checks passed!

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
✅ 4. 에러 수정
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

에러 없음 - 모든 검증 통과

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
📦 5. Git Commit
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Staged: 11 files

커밋 메시지:
feat(claude): Agent 6개, Skill 5개 추가

- query-decomposition: 자연어 질문 분해
- option-generator: 대안 3개 생성
- impact-simulator: As-Is/To-Be 시뮬레이션
- success-probability: 성공확률 산출
- validator: 근거 검증/환각 탐지
- workflow-builder: 실행 Workflow 생성
- project-plan skill: 프로젝트 계획 수립
- capacity-forecast skill: 가동률 병목 예측 (A-1)
- go-nogo skill: Go/No-go 분석 (B-1)
- headcount-analysis skill: 증원 원인분해 (C-1)
- competency-gap skill: 역량 갭 분석 (D-1)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

[main abc1234] feat(claude): Agent 6개, Skill 5개 추가
 11 files changed, 1500 insertions(+)

✅ 프로젝트 정리 완료!

옵션

옵션	설명	기본값
`--skip-test`	테스트 건너뛰기	false
`--skip-docs`	문서 업데이트 건너뛰기	false
`--no-commit`	커밋하지 않고 준비만	false
`--amend`	이전 커밋 수정	false
`--push`	커밋 후 푸시	false
`--dry-run`	실제 실행 없이 미리보기	false

에러 처리

에러	메시지	해결 방법
테스트 실패	"N개 테스트 실패"	에러 수정 후 재실행
타입 에러	"타입 검사 실패"	타입 수정 필요
린트 에러	"린트 검사 실패"	`--fix` 시도 또는 수동 수정
변경사항 없음	"커밋할 변경사항 없음"	작업 확인
Git 충돌	"병합 충돌 발생"	충돌 해결 후 재시도

사용법

code

/project-cleanup                    # 기본 실행 (테스트 + 문서 + 커밋)
/project-cleanup --dry-run          # 미리보기
/project-cleanup --skip-test        # 테스트 건너뛰기
/project-cleanup --push             # 커밋 후 원격 푸시
/project-cleanup --no-commit        # 테스트/문서만, 커밋 안 함

연계 Skill/Agent

Skill/Agent	역할	연계 방식
orchestrator	워크플로 조율	단계별 실행 관리
validator	변경사항 검증	문서-코드 일치 확인

SSDD 원칙 체크리스트

문서 업데이트 시

• 명세 먼저, 구현은 명세 따라
• 변경사항은 반드시 문서에 반영
• 버전 번호는 변경 규모에 맞게
• 날짜는 KST 기준 YYYY-MM-DD
• 중복 없이 한 곳에만 기록

커밋 전 확인

• 모든 테스트 통과
• 타입/린트 검사 통과
• 문서 동기화 완료
• 커밋 메시지 규칙 준수
• Co-Author 태그 포함