sir-ad/claude-setup-skill

/claude-setup

현재 프로젝트에 맞는 .claude/ 디렉토리를 스캐폴딩합니다. 코드베이스를 읽고, 컨텍스트를 감지하며, 이 스택에 실제로 필요한 파일만 생성합니다.

이 스킬의 철칙: 카고컬트(cargo-cult)를 생성하지 마세요. 빈 폴더는 없습니다. 일반적인 플레이스홀더도 없습니다. 규칙, 스킬 또는 에이전트가 이 프로젝트에 존재할 실질적인 이유가 없다면 건너뜁니다.

---

1단계: 감지

다음 명령어를 병렬로 실행하고 출력을 분석합니다:

!pwd && echo "---" && ls -la !cat README.md 2>/dev/null | head -120 !cat package.json Cargo.toml pyproject.toml go.mod Gemfile pom.xml build.gradle build.gradle.kts deno.json bun.lockb 2>/dev/null | head -300 !ls .claude/ 2>/dev/null && echo "---기존 클로드 설정 끝---" !cat .gitignore 2>/dev/null | head -60 !ls docs/ docs/rfcs/ docs/adr/ docs/architecture/ 2>/dev/null

출력 결과를 바탕으로 다음을 결정합니다:

• 스택: Rust (Cargo.toml), Node/TS (package.json), Python (pyproject.toml/requirements.txt), Go (go.mod), Ruby (Gemfile), Java/Kotlin (pom.xml/build.gradle), Deno (deno.json), Bun 또는 혼합. 여러 개일 경우 주된 것을 선택하고 부차적인 것을 기록합니다.
• 레이아웃: 모노레포 (workspaces/turbo/nx/lerna/cargo [workspace]/Go workspace) 또는 단일 프로젝트.
• 기존 .claude/: 존재한다면 병합입니다 — 파일별 확인 없이 덮어쓰지 마세요.
• README/RFC/ADR에서 추출한 하드 룰: "locked", "banned", "no ", "must ", "RFC", "ADR-NNN", "invariant" 같은 단어가 신호입니다. 실제 룰만 인코딩하세요 — 지어내지 마세요.
• 테스트 프레임워크, 린터, 포맷터, 패키지 매니저 — 설정 파일과 스크립트에서 추출하여 CLAUDE.md의 명령어가 실제로 동작하도록 합니다.

감지가 진정으로 모호한 경우(여러 개의 lockfile, 명확한 주 언어 없음, README 없음), 중단하고 사용자에게 하나의 집중된 질문을 해서 해결하세요. 감지할 수 있는 것에 대해 묻지 마세요.

---

2단계: 일치하는 템플릿 읽기

이 스킬에 번들된 템플릿은 스택별로 무엇을 생성할지 설명합니다. 해당하는 것을 읽으세요 (${CLAUDE_SKILL_DIR}/templates/<name>.md 사용):

• rust-workspace.md — Cargo [workspace]
• rust-single.md — 단일 Cargo.toml
• node-monorepo.md — npm/yarn/pnpm workspaces, turbo, nx, lerna
• node-single.md — 단일 package.json (Next.js, Vite, Express 등)
• python.md — Poetry, pip+venv, uv, hatch
• go.md — go.mod 프로젝트
• generic.md — 그 외의 경우

각 템플릿은 CLAUDE.md에 포함할 내용, 어떤 권한이 중요한지, 어떤 경로 범위 규칙이 유용한지, 코드 리뷰어 하위 에이전트를 조정하는 방법, 그리고 해당 스택에 일반적으로 유용한 스킬을 나열합니다.

템플릿은 참고 자료일 뿐, 붙여 넣을 보일러플레이트가 아닙니다. 무엇을 생성할지 결정하는 데 사용하고, 출력은 이 프로젝트에 맞게 작성하세요.

---

3단계: 계획 수립 및 확인

파일을 쓰기 전에 사용자에게 계획을 출력합니다:

감지됨: <stack> (<layout>)
프로젝트 이름: <name>
주요 명령어: build=<cmd>, test=<cmd>, lint=<cmd>

생성할 항목:
  CLAUDE.md                                  (NEW | MERGE | SKIP)
  .worktreeinclude                           (NEW | SKIP)
  .claude/settings.json                      (NEW)
  .claude/rules/<n>.md                       (NEW, path: <glob>)
  .claude/agents/<lang>-reviewer.md          (NEW)
  .claude/skills/<n>/SKILL.md                (NEW)

건너뛸 항목 (명확한 사용 사례 없음): output-styles/, commands/, agent-memory/

기존 파일: <action: keep/replace/merge와 함께 목록>

README/RFC에서 감지된 하드 룰:
  - <인용문 1> → rules/<file>.md에 인코딩됨
  - <인용문 2> → CLAUDE.md에 인코딩됨

진행할까요? [y/N/preview/edit-plan]

--dry-run인 경우: 여기서 멈춥니다.

파일이 이미 존재하는 경우, 기본 동작은 유지(keep) 입니다. 교체 전에 확인을 요청하세요.

--minimal인 경우: CLAUDE.md + .claude/settings.json만 계획합니다.

--skip-skills인 경우: 계획에서 skills/를 생략합니다.

---

4단계: 생성

계획에 따라 파일을 작성합니다. 파일별 규칙:

CLAUDE.md

• 상단: 스택 한 줄 요약.
• ## Commands 블록: package.json 스크립트 / Makefile / Cargo alias / pyproject 스크립트에서 추출한 실제 명령어. 존재하지 않는 명령어는 나열하지 마세요.
• ## Repo map 블록: 중요한 디렉토리만. node_modules, target, dist, .next, __pycache__는 건너뛰세요.
• ## Hard rules: README/RFC/ADR에서 가져온 것만. 내용이 없으면 섹션을 생략하세요 — 채우지 마세요.
• ## Behavioral principles: 기존 CLAUDE.md에 사용자의 원칙이 이미 있다면 유지하고, 그렇지 않으면 생략하세요 (전역 ~/.claude/CLAUDE.md가 이미 다룰 가능성이 높습니다).

.claude/settings.json

• permissions.allow: 스택에 맞게 조정. Rust의 경우: cargo *, git diff *, gh *. Node의 경우: npm test *, npm run *, pnpm *. 포괄적인 Bash(*)는 허용하지 마세요.
• permissions.deny: 최소 rm -rf *, git push --force *, git reset --hard *. 스택별 파괴적 명령어 추가 (예: 라이브러리의 경우 npm publish *).
• 프로젝트에 명확한 사전/사후 도구 요구 사항이 없으면 훅을 추가하지 마세요.

.claude/rules/<name>.md

실제 규칙이 있는 디렉토리에만 경로 범위 규칙을 적용합니다. 휴리스틱:

• 모노레포: 고유한 규칙이 있는 워크스페이스 멤버당 하나의 규칙.
• 테스트 규칙: 프로젝트에 명확하지 않은 테스트 규칙이 있는 경우 **/*test* 패턴에 적용되는 하나의 규칙.
• 인프라/IaC: 프로젝트에 IaC가 있는 경우 infra/**에 적용되는 하나의 규칙.
• API 설계: 명확한 형태 계약이 있는 경우 API 경로에 적용되는 하나의 규칙.

문서 예제에 규칙이 있다고 해서 생성하지 마세요. CLAUDE.md로 규칙이 명확하다면 규칙이 필요하지 않습니다.

.claude/agents/<lang>-reviewer.md

• 도구: Read, Grep, Glob만 (읽기 전용).
• 본문: 언어별 체크리스트 (템플릿 참조).
• 설명은 Claude가 리뷰 작업에 대해 자동으로 호출할 수 있을 만큼 구체적이어야 함: "다음에 대한 변경 사항을 리뷰합니다..." — 특정 검사 항목을 나열하세요.

.claude/skills/<n>/SKILL.md

명확하고 반복 가능한 워크플로우가 있는 스킬만 생성:

• /release — 프로젝트에 버전 파일 (Cargo.toml, package.json, pyproject.toml) 과 CHANGELOG.md가 모두 있는 경우.
• /test — 간단하지 않은 테스트 명령어가 있는 경우 (예: 매트릭스, 여러 스위트). 단일 cargo test는 스킬이 필요하지 않습니다.
• /lint — 동일한 로직.
• 스택별 (예: Django/Rails의 /db-migrate, Next.js의 /deploy-preview).

TODO 본문이 있는 플레이스홀더 스킬은 생성하지 마세요. 작동하거나 건너뛰거나, 중간은 없습니다.

.worktreeinclude

• 워크트리에 필요한 gitignored 파일 나열: .env, .env.local.
• CLAUDE.md 또는 .mcp.json이 gitignored된 경우 (.gitignore 확인), 포함시켜 워크트리가 맹목적으로 작업하지 않도록 합니다.
• .claude/settings.local.json이 gitignored된 경우 포함시킵니다.

---

5단계: 확인 및 보고

파일 작성 후:

echo "=== 생성된 트리 ==="
find .claude -type f | sort
echo "=== 라인 수 ==="
find .claude -type f -exec wc -l {} \;

다음을 출력합니다:

1. 최종 트리.
2. 라인 수 (목표: 각 파일 ≤ 100줄; 150줄 초과 시 플래그).
3. 한 가지 구체적인 확인 단계 (예: "세션을 열고 /permissions를 실행하여 cargo *가 커밋된 것으로 표시되는지 확인").
4. 알림: 아직 .gitignore에 .claude/settings.local.json을 추가하지 않았다면 추가.

---

방지 목표 (명확히 재진술)

1. 빈 폴더 없음. 실제 스타일이 없으면 output-styles/ 없음. commands/ 없음 (스킬이 대체, Anthropic 문서 기준).
2. 문서 예제에서 복사-붙여넣기 금지. 표준 트리의 testing.md와 api-design.md는 예제입니다 — 이 프로젝트에 실제로 해당 규칙이 있는 경우에만 유사한 것을 생성하세요.
3. 덮어쓰기 금지. 항상 파일별로 교체를 확인하세요.
4. 무에서 하드 룰을 생성하지 마세요. README/RFC/ADR에서 가져오세요. 존재하지 않으면 프로젝트에 하드 룰이 없는 것입니다 — 그렇게 말하고 넘어가세요.
5. TODO가 있는 스킬 금지. 작동하거나 건너뛰거나.
6. 권한에 글로벌 와일드카드 금지. Bash(cargo *)는 되지만 Bash(*)는 안 됩니다.

---

플래그 참조

• --minimal: CLAUDE.md + .claude/settings.json만.
• --skip-skills: skills/ 생략.
• --dry-run: 계획 출력, 아무것도 쓰지 않음.

(모든 플래그는 선택 사항입니다. 기본값은 전체 표준 레이아웃이며, 스택을 인식하고 확인 절차를 포함합니다.)