/setup 스킬

프로젝트의 .claude/profile.json을 읽어 스택에 맞는 CLAUDE.md를 자동 생성한다.

동작 흐름

profile.json 존재 → Step 2로 바로 진행 (기존 파싱)
profile.json 없음 → Step 1 대화형 온보딩

ARGUMENT 처리

$ARGUMENTS 없음     → .claude/profile.json 자동 탐색
$ARGUMENTS 있음     → 파일 경로로 인식 (예: /setup .claude/profile.json)
$ARGUMENTS --profile → 코딩 프로필 생성만 실행 (아래 "코딩 프로필" 섹션 참조)

코딩 프로필 (/setup --profile)

/setup --profile 또는 "코딩 스타일 분석해줘" 요청 시 실행. /setup 기본 흐름에서는 묻지 않는다.

흐름:

1. Step 1에서 감지한 스택 정보(또는 package.json 분석)를 기반으로 분석 카테고리를 동적 선택
2. 프로젝트 코드를 실제로 읽고 (주요 디렉토리에서 2-3개 파일 샘플링) 패턴 분석
3. 결과를 .candidate/profile.md에 저장 (레거시 .claude/coding-profile.md 는 폴백으로만)
4. 사용자에게 결과 보여주고 수정 여부 확인

스택별 분석 카테고리 (동적 선택):

감지 못한 스택이면: 범용 카테고리(추상화, 에러, 네이밍, 폴더, 커밋)만 분석 + Claude가 코드를 읽고 해당 언어에 맞는 질문 동적 생성

참조 템플릿: ${CLAUDE_PLUGIN_ROOT}/.candidate/code-analysis-prompt.md (React/TS 예시)

생성 경로: .candidate/profile.md (local, 우선) 또는 ~/.claude/coding-profile.md (global, 레거시 폴백)

선택 UI 규칙

모든 선택은 AskUserQuestion 도구를 사용하여 인터랙티브 선택 UI로 제시한다. 텍스트로 > 커서를 출력하거나 숫자/Y/n 입력을 받지 않는다.

구현 방식

1. AskUserQuestion 도구를 호출하여 클릭 가능한 선택지를 보여준다
2. 감지된 항목이 있으면 해당 옵션의 label에 (Recommended) 를 붙여 첫 번째에 배치한다
3. options에 없는 선택은 사용자가 "Other"를 통해 자유 입력할 수 있다 (자동 제공됨)
4. 한 번에 최대 4개 질문까지 묶을 수 있지만, 의존 관계가 있으면 순차적으로 묻는다

예시

AskUserQuestion({
  questions: [{
    question: "이 설정을 어디에 적용할까요?",
    header: "설치 위치",
    options: [
      { label: "이 프로젝트에만 (.claude/)", description: "현재 프로젝트에만 적용" },
      { label: "전역 설정 (~/.claude/)", description: "모든 프로젝트에 적용" }
    ],
    multiSelect: false
  }]
})

핵심: 한 번에 하나만 묻고, 응답을 받은 후 다음으로 넘어간다. 반드시 AskUserQuestion 도구를 사용한다.

Step 1: 대화형 온보딩 (profile.json 없을 때)

.claude/profile.json이 없으면 아래 서브스텝을 순차 진행한다. 한 번에 하나씩 질문하고, 사용자 응답을 받은 후 다음으로 넘어간다.

참고: 아래의 > 옵션 형식 예시들은 AskUserQuestion 도구에 전달할 옵션 내용의 참고 자료이다. 실제 구현 시 반드시 AskUserQuestion 도구를 호출하여 인터랙티브 선택 UI로 표시한다. 텍스트로 > 커서를 출력하지 않는다.

1-0. 설치 위치 선택

code-forge 설정을 시작합니다.

이 설정을 어디에 적용할까요?

> 이 프로젝트에만 (.claude/)
  전역 설정 (~/.claude/)

1-1. package.json 자동 감지 + 프로젝트 유형 판별

package.json이 존재하면 dependencies를 분석하여 스택을 자동 추론한다.

프로젝트 유형 판별:

먼저 프로젝트가 프론트엔드 서비스인지 판별한다.

서비스가 아닌 경우:

이 프로젝트는 프론트엔드 서비스가 아닌 것 같습니다.
(감지: CLI 도구 / 라이브러리 / 스택 미감지)

스택 모듈 설정이 필요한가요?

> 건너뛰기 (명령어 + 기능 설정만)
  아니요, 스택 설정도 할게요

→ "건너뛰기" 선택 시: 1-2, 1-3을 건너뛰고 1-4(프로젝트 정보)로 직행 → "스택 설정도 할게요" 선택 시: 정상 진행

감지 규칙 (서비스인 경우):

추가 감지:

미매칭 라이브러리 감지:

감지 규칙에 매칭되지 않는 관련 라이브러리가 있으면 해당 카테고리의 "기타" 옵션으로 자동 추가한다.

예시:

• recoil 감지 → State 카테고리에 recoil (감지됨) 옵션 동적 추가
• sass 감지 → Styling 카테고리에 sass (감지됨) 옵션 동적 추가
• @testing-library/react 있지만 jest/vitest 없음 → Testing에 해당 정보 표시

카테고리별 감지 확장 규칙:

감지되면 해당 카테고리 옵션 목록에 {라이브러리명} (감지됨) 형태로 자동 삽입한다.

프로젝트 정보 자동 추출:

package.json의 scripts에서 dev, build, lint, test 명령어를 추출한다. 패키지 매니저는 lock 파일로 판단: yarn.lock → yarn, pnpm-lock.yaml → pnpm, 그 외 → npm.

package.json을 분석합니다...

감지된 스택:
  Framework:     next (14.2.x) → react-nextjs-app
  State:         jotai (2.x) + @tanstack/react-query (5.x) → jotai-tanstack
  Styling:       @emotion/styled (11.x) → emotion
  Testing:       vitest (1.x) → vitest
  Design System: 감지 안 됨

감지된 명령어:
  dev:   yarn dev
  build: yarn build
  lint:  yarn lint
  test:  yarn test

package.json이 없으면 이 단계를 건너뛰고 1-3으로 직행한다.

1-2. 프리셋 매칭 및 제안

감지 결과를 기존 프리셋과 비교한다.

매칭 알고리즘:

• 감지된 modules와 preset.json의 modules를 비교
• 모든 필드 일치 → "일치합니다"
• 80%+ 일치 → "유사합니다 (차이: X)"
• 그 외 → "매칭 없음"

프리셋 매칭 시:

감지 결과가 "standard" 프리셋과 일치합니다.

  standard: Pages Router + Jotai + Emotion + Jest

> standard 프리셋으로 진행
  직접 선택할게요

→ "standard 프리셋으로 진행" 선택 시: 1-4로 건너뜀 (프로젝트 정보 확인) → "직접 선택할게요" 선택 시: 1-3으로 진행

프리셋 매칭 안 될 때:

사용 가능한 프리셋:

> standard — Pages Router + Jotai + Emotion + Jest
  modern-stack — MUI + App Router + Zustand + Tailwind + Vitest
  backend-api — Node.js Express + TypeScript + Jest
  직접 선택 (감지 결과 기반)

1-3. 카테고리별 순차 질문

직접 선택 시 한 번에 한 카테고리씩 질문한다. 자동 감지 결과가 있으면 해당 항목에 > 커서를 놓는다 (기본 선택).

각 카테고리마다 "기타" 옵션이 있다. 감지되었지만 옵션에 없는 라이브러리는 자동으로 옵션에 추가된다.

[1/5] Framework

> react-nextjs-app — Next.js App Router     ← 감지됨
  react-nextjs-pages — Next.js Pages Router
  react-spa — React SPA (Vite/CRA)
  기타 (직접 입력)

[2/5] Design System

> 없음
  mui — Material UI
  ant-design — Ant Design
  기타 (직접 입력)

[3/5] State Management

> jotai-tanstack — Jotai + TanStack Query   ← 감지됨
  zustand-tanstack — Zustand + TanStack Query
  redux-rtk — Redux Toolkit + RTK Query
  기타 (직접 입력)

감지되었지만 옵션에 없는 경우 (예: recoil 감지):

[3/5] State Management

> recoil — Recoil                            ← 감지됨
  jotai-tanstack — Jotai + TanStack Query
  zustand-tanstack — Zustand + TanStack Query
  redux-rtk — Redux Toolkit + RTK Query
  기타 (직접 입력)

[4/5] Styling

> emotion — Emotion (@emotion/styled)       ← 감지됨
  tailwind — Tailwind CSS
  styled-components — Styled Components
  기타 (직접 입력)

[5/5] Testing

> vitest — Vitest                            ← 감지됨
  jest — Jest
  기타 (직접 입력)

"기타" 선택 시 동작:

[3/5] State Management

사용 중인 상태 관리 라이브러리를 입력해 주세요:
> recoil

입력값은 modules.state에 문자열로 저장된다. 대응하는 모듈 SKILL.md가 없으면 규칙 참조에서 제외되지만, profile.json에는 기록되어 CLAUDE.md 스택 섹션에 표시된다.

1-4. 프로젝트 정보 확인

자동 감지된 명령어를 보여주고 확인받는다.

[프로젝트 정보]

  프로젝트명: my-app (package.json name)
  dev:   yarn dev
  build: yarn build
  lint:  yarn lint
  test:  yarn test

> 이대로 진행
  수정할게요

→ "수정할게요" 선택 시: 각 항목을 하나씩 다시 질문

package.json이 없었으면 각 항목을 직접 물어본다:

[프로젝트 정보]

프로젝트 이름을 입력해 주세요:
>

개발 서버 명령어 (예: yarn dev):
>

빌드 명령어 (예: yarn build):
>

린트 명령어 (예: yarn lint):
>

테스트 명령어 (예: yarn test):
>

1-5. 최종 확인

설정 요약

  설치 위치:     이 프로젝트 (.claude/)
  프리셋:        없음 (커스텀)

  Framework:     react-nextjs-app     → Next.js App Router
  Design System: 없음
  State:         jotai-tanstack       → Jotai + TanStack Query v5
  Styling:       emotion              → Emotion (@emotion/styled)
  Testing:       vitest               → Vitest

  프로젝트명: my-app
  dev:   yarn dev
  build: yarn build
  lint:  yarn lint
  test:  yarn test

> 생성
  처음부터 다시

→ "생성": profile.json 생성 후 Step 2로 진행 → "처음부터 다시": 1-0부터 재시작

파일이 있는 경우 — 파싱

// .claude/profile.json 예시
{
  "installTarget": "local",          // "local" | "global" (기본: "local")
  "projectType": "service",          // "service" | "library" | "cli" | "other"
  "preset": "standard",              // 프리셋 사용 (선택)
  "modules": {                       // 개별 모듈 직접 선택 (선택)
    "framework": "react-nextjs-pages",
    "state": "jotai-tanstack",
    "styling": "emotion",
    "testing": "jest"
  },
  "project": {                       // 프로젝트 기본 정보 (선택)
    "name": "my-project",
    "dev": "yarn dev",
    "build": "yarn build",
    "lint": "yarn lint",
    "test": "yarn test"
  },
  "overrides": {}                    // 앱별 오버라이드 (선택)
}

Step 2: 모듈 해석

프리셋 우선순위 규칙

1. preset 필드가 있으면 ${CLAUDE_PLUGIN_ROOT}/presets/{preset}.json 로드
2. preset의 modules를 기본값으로 설정
3. profile.json의 modules 명시값으로 덮어씀
4. overrides 병합

커스텀 모듈 처리

modules의 값이 알려진 모듈 목록에 없으면 (예: "state": "recoil"):

• 대응하는 SKILL.md가 없으므로 규칙 참조에서 제외
• CLAUDE.md 스택 섹션에는 입력값 그대로 표시 (예: State: recoil)
• 에러 없이 정상 진행

모듈 → SKILL.md 경로 매핑

Step 3: CLAUDE.md 생성

아래 템플릿으로 50줄 이내의 CLAUDE.md를 생성한다. installTarget에 따라 생성 경로가 달라진다.

모듈 컨벤션 상세는 CLAUDE.md에 포함하지 않는다. 에이전트는 @${CLAUDE_PLUGIN_ROOT}/modules/... 참조로 직접 읽는다.

CLAUDE.md 템플릿

# {project.name} CLAUDE.md

> 자동 생성: /setup 스킬 | 수정 시 profile.json을 변경 후 /setup 재실행

## 스택

- Framework: {framework 설명}
- Design System: {design-system 설명}
- State: {state 설명}
- Styling: {styling 설명}
- Testing: {testing 설명}

## 명령어

```bash
# 개발
{project.dev}

# 빌드
{project.build}

# 린트
{project.lint}

# 테스트
{project.test}

규칙 참조

@{CLAUDE_PLUGIN_ROOT}/modules/frameworks/{framework}/SKILL.md @{CLAUDE_PLUGIN_ROOT}/modules/design-systems/{design-system}/SKILL.md @{CLAUDE_PLUGIN_ROOT}/modules/state/{state}/SKILL.md @{CLAUDE_PLUGIN_ROOT}/modules/styling/{styling}/SKILL.md @{CLAUDE_PLUGIN_ROOT}/modules/testing/{testing}/SKILL.md

**projectType이 "service"가 아닌 경우:**
- 스택 섹션과 규칙 참조 섹션을 생략
- 명령어 섹션만 포함

### 스택 설명 매핑

| 모듈값              | 설명                          |
| ------------------- | ----------------------------- |
| react-nextjs-pages  | Next.js 14 Pages Router       |
| react-nextjs-app    | Next.js App Router            |
| react-spa           | React SPA (Vite/CRA)          |
| mui                 | Material UI                   |
| ant-design          | Ant Design                    |
| jotai-tanstack      | Jotai + TanStack Query v5     |
| zustand-tanstack    | Zustand + TanStack Query v5   |
| redux-rtk           | Redux Toolkit + RTK Query     |
| emotion             | Emotion (@emotion/styled)     |
| tailwind            | Tailwind CSS                  |
| styled-components   | Styled Components             |
| jest                | Jest                          |
| vitest              | Vitest                        |

매핑에 없는 값 (커스텀 입력)은 입력값 그대로 표시한다.

---

## Step 3-2: AGENTS.md 생성 (Codex/멀티툴 호환)

CLAUDE.md와 동일한 경로에 `AGENTS.md`를 생성한다.
Codex CLI, GitHub Copilot 등 AGENTS.md를 읽는 도구에 사고모델 핵심을 전파한다.

| installTarget | 경로 |
|--------------|------|
| `local` | `./AGENTS.md` |
| `global` | `~/.claude/AGENTS.md` |

기존 AGENTS.md가 있으면 **건드리지 않는다** (사용자 커스텀 존중).

### AGENTS.md 템플릿

```markdown
# {project.name} AGENTS.md

> 자동 생성: code-forge /setup | CLAUDE.md와 함께 사용

## Working Protocol

모든 코드 작업에 아래 규칙을 따른다:

1. **읽기 우선** — 수정 전 반드시 파일을 읽는다. 기억에서 추론하지 않는다
2. **패턴 준수** — 기존 코드의 구조, 네이밍, 스타일을 따른다
3. **정책 보존** — 비즈니스 로직을 임의 변경하지 않는다
4. **최소 변경** — 요청받은 것만 수정한다
5. **스코프 준수** — 대상 외 파일은 명시 요청 없이 수정하지 않는다

작업 루프: GROUND(맥락 파악) → APPLY(구현) → VERIFY(검증) → ADAPT(실패 시 조정)

## Project Conventions

Read CLAUDE.md for stack-specific rules, commands, and module references.

projectType이 "service"가 아닌 경우에도 동일하게 생성한다 (사고모델은 스택 무관).

Step 4: 결과 요약 출력

/setup 완료

프로젝트: {project.name}
설치 위치: {installTarget}
스택:
  Framework:     react-nextjs-app   → Next.js App Router
  State:         jotai-tanstack     → Jotai + TanStack Query v5
  Styling:       emotion            → Emotion (@emotion/styled)
  Testing:       vitest             → Vitest

생성된 파일:
  CLAUDE.md (47줄)
  AGENTS.md (사고모델 핵심 — Codex/멀티툴 호환)
  .claude/profile.json

참조 모듈 (4개):
  @{CLAUDE_PLUGIN_ROOT}/modules/frameworks/react-nextjs-app/SKILL.md
  @{CLAUDE_PLUGIN_ROOT}/modules/state/jotai-tanstack/SKILL.md
  @{CLAUDE_PLUGIN_ROOT}/modules/styling/emotion/SKILL.md
  @{CLAUDE_PLUGIN_ROOT}/modules/testing/vitest/SKILL.md

다음 단계:
  - CLAUDE.md 내용을 확인하세요
  - 빌드/린트 명령어가 올바른지 확인하세요
  - profile.json의 overrides로 앱별 설정을 추가할 수 있습니다

Step 5: code-forge.local.md 생성

CLAUDE.md 생성 완료 후, 프로젝트 로컬 설정 파일을 생성한다. 이미 존재하면 version 필드만 업데이트한다.

plugin.json에서 현재 버전을 읽어온다: ${CLAUDE_PLUGIN_ROOT}/.claude-plugin/plugin.json → version 필드.

---
version: {plugin.json의 version}
plugins:
  smith:
    enabled: false
---

• version: 이 프로젝트에 적용된 code-forge 버전. 플러그인 업데이트 후 /setup 재실행 시 버전 차이를 감지하여 CLAUDE.md를 재생성한다.
• plugins.smith: /code-forge:smith-setup에서 확장한다. 초기값은 enabled: false.

Step 6: Smith 활성화 여부

스택 설정 완료 후, 프로젝트 전용 에이전트 생성 여부만 묻는다. Whetstone/Bellows는 묻지 않고 기본값으로 세팅 — 나중에 code-forge.local.md에서 직접 편집 가능.

Smith (프로젝트 전용 에이전트)
프로젝트를 분석하여 레포 맞춤 에이전트를 자동 생성합니다.

> 사용 (권장)
  사용 안 함

설정 결과 저장

응답에 따라 code-forge.local.md에 저장:

plugins:
  smith:
    enabled: true     # 사용자 선택 반영
  whetstone:
    enabled: false    # 기본 off (별도 레포, 원하면 직접 true로)
  bellows:
    enabled: true     # 기본 on (로컬 사용량 로깅, $HOME/.code-forge/usage.jsonl)

Step 7: Smith 자동 호출 (orchestrator)

Smith가 활성화된 경우 setup 스킬 내부에서 즉시 다음 서브 스킬을 실행한다. 사용자에게 추가 질문하지 않는다. 사용자가 Step 6에서 "사용"을 선택한 것이 곧 실행 동의다.

Smith enabled = true인 경우

[즉시 실행] Skill 도구로 code-forge:smith-create-agent를 호출한다.

• 호출 전 안내 1줄: Smith 에이전트를 생성합니다...
• smith-create-agent는 이미 생성된 profile.json을 재사용 (Step 5 결과물)
• 생성 완료 후 setup으로 복귀해 Step 8 요약 출력
• 호출이 실패하면 안내 1줄만 출력하고 setup 전체는 성공 처리:

  Smith 에이전트 생성 중 오류. 수동으로 /code-forge:smith-create-agent 재시도하세요.

Smith enabled = false인 경우

다음 안내만 출력하고 Step 8로 진행:

(나중에 Smith를 쓰려면 /code-forge:smith-create-agent 실행)

Step 8: 설정 완료 안내

설정이 완료되었습니다.

이 설정은 code-forge.local.md에 저장됩니다.
나중에 변경하려면:
  /code-forge:smith-setup    → Smith on/off
  code-forge.local.md        → 직접 편집 (whetstone/bellows 토글)

CLAUDE.md 백업 안내

기존 CLAUDE.md가 있는 경우:

기존 CLAUDE.md가 발견되었습니다.

> 백업 후 새로 생성 (기존 → .claude/CLAUDE.md.bak)
  기존 내용과 합치기 (하단에 code-forge 설정 추가)
  취소

"기존 내용과 합치기" 선택 시 기존 내용을 보존하면서 스택/명령어/모듈 참조만 추가한다.

에러 처리

알려진 프리셋