/smith-create-agent

name: smith-create-agent
description: 프로젝트를 분석하여 Smith 2.0 에이전트를 생성한다. STATE class 조합과 ACT class를 선택하여 instance 에이전트를 만든다. "에이전트 만들어줘", "Smith 에이전트 생성", "create agent", "에이전트 세팅" 등의 요청에 사용한다.
category: setup
agent-system: Smith

Smith Create Agent

프로젝트를 분석하고 Smith 2.0 에이전트 정의 파일을 생성하는 스킬.

호출 경로

| 경로 | 동작 | |------|------| | 사용자 직접 (`/code-forge:smith-create-agent`) | Step 1부터 풀 실행 — 프로젝트 분석 + 대화형 확인 | | `/code-forge:setup`에서 위임 호출 (orchestrator) | **Step 1 스킵** — `.claude/profile.json`이 이미 Step 5에서 생성됐으므로 재사용. 즉시 Step 2 Deep Analysis부터 시작 |

**위임 감지 방법**: `.claude/profile.json`이 현재 턴에 이미 존재하면 setup으로부터 위임된 호출로 간주한다. 사용자 재확인 질문을 생략하고 분석/생성 파이프라인으로 직행한다.

References

• `references/subagent-spec.md` — Claude Code subagent frontmatter 필드 전체 규격

기본 생성 구조

**최소 8개 파일을 기본으로 생성하되, 프로젝트 성격에 따라 추가 에이전트를 자유롭게 생성한다:**

.agents/agents/
├── {project}-domain.md      (class, STATE) ← 도메인 모델/용어/플로우
├── {project}-policy.md      (class, STATE) ← SSOT/금지 영역/규칙
├── {project}-context.md     (class, STATE) ← 디렉토리 맵/추상화/패턴
├── {project}-base.md        (class, STATE) ← extends: framework+language+위 3개
├── {project}-architect.md   (instance) ← 분석/설계
├── {project}-dev.md         (instance) ← 개발/구현
├── {project}-reviewer.md    (instance) ← 코드 리뷰
├── {project}-tester.md      (instance) ← 테스트 작성
├── .analysis-manifest.json  ← 분석 메타데이터 (staleness 감지용)
└── ... 프로젝트에 필요한 만큼 추가

Deep Analysis Pipeline (Step 2)

프로젝트 분석을 4축 병렬로 수행한다:

**2-1. 기술 스택 스캔** (기존 유지)

• package.json, tsconfig.json 등에서 기술 스택 파악

**2-2. 도메인 분석** (신규)

• 타입 정의, API 라우트, DB 스키마, 상태 관리, README에서 교차 검증
• 핵심 엔티티, 비즈니스 플로우, 도메인 용어 추출
• → `{project}-domain.md` 생성

**2-3. 정책 분석** (신규)

• CLAUDE.md, ESLint, tsconfig, CI, CODEOWNERS에서 추출
• SSOT 위치, 수정 금지 영역, import 규칙, PR/커밋 규칙
• → `{project}-policy.md` 생성

**2-4. 컨텍스트 분석** (신규)

• 디렉토리 트리, import 빈도, shared 파일에서 추론
• 아키텍처 패턴 (레이어드, DDD, feature-based 등) 자동 분류
• → `{project}-context.md` 생성

base class extends 확장

기존: `framework + language`만 extends 변경: `framework + language + domain + policy + context` extends → instance는 변경 불필요 (투명한 확장)

--refresh 모드

`.analysis-manifest.json`의 `analyzedAt`으로부터 30일 이상 경과 시 재분석 권장. 변경된 축만 선택적으로 재분석하고, 사용자 정의 규칙(userDefinedRules)은 보호.

추가 에이전트 예시

프로젝트 분석 결과에 따라 아래와 같은 에이전트를 추가로 생성할 수 있다:

| 상황 | 추가 에이전트 | ACT class | |------|-------------|-----------| | 풀스택 프로젝트 | `{project}-fe-dev.md`, `{project}-be-dev.md` | `act/dev/implementor.md` (state로 fe/be 분리) | | 보안 중요 프로젝트 | `{project}-security.md` | `act/quality/security-reviewer.md` | | 리팩토링 중인 프로젝트 | `{project}-refactorer.md` | `act/dev/refactorer.md` | | 버그 트래킹 필요 | `{project}-bug-fixer.md` | `act/dev/bug-fixer.md` | | Git 워크플로우 복잡 | `{project}-git-ops.md` | `act/ops/git-operator.md` | | 테스트 케이스 도출 분리 | `{project}-spec-analyst.md` | `act/analysis/spec-to-testcase.md` |

기본 5개에 제한되지 않는다. 프로젝트를 분석한 뒤 필요한 역할을 모두 생성하라.

역할별 기본 ACT 매핑

| 역할 | ACT class | |------|-----------| | architect | `${CLAUDE_PLUGIN_ROOT}/plugins/smith/agents/act/analysis/requirement-analyst.md` | | dev | `${CLAUDE_PLUGIN_ROOT}/plugins/smith/agents/act/dev/implementor.md` | | reviewer | `${CLAUDE_PLUGIN_ROOT}/plugins/smith/agents/act/quality/reviewer.md` | | tester | `${CLAUDE_PLUGIN_ROOT}/plugins/smith/agents/act/dev/assayer.md` |

ACT class의 `## Permission` 섹션에서 `model`, `tools`, `permissionMode`를 자동 추출하여 instance frontmatter에 적용한다.

tools / permissionMode — ACT class에서 자동 추출

instance의 `tools`와 `permissionMode`는 하드코딩하지 않는다. 매핑된 ACT class 파일의 `## Permission` 섹션에서 읽어온다:

1. ACT class 파일을 읽는다 2. `[Tools]` 값 → instance frontmatter의 `tools` 필드에 적용 3. `[PermissionMode]` 값 → instance frontmatter의 `permissionMode` 필드에 적용 4. `[Model]` 값 → instance frontmatter의 `model` 필드에 적용

ACT class에 값이 없으면 상위(`act.md`)의 기본값을 사용한다:

• `tools`: `Read, Grep, Glob`
• `permissionMode`: `bypassPermissions`
• `model`: `sonnet`

기본 스킬 매핑

| 역할 | 스킬 | |------|------| | architect | `superpowers:brainstorming`, `superpowers:writing-plans`, `investigate` | | dev | `superpowers:test-driven-development`, `superpowers:executing-plans`, `superpowers:verification-before-completion` | | reviewer | `code-review:code-review`, `simplify`, `superpowers:verification-before-completion` | | tester | `superpowers:test-driven-development`, `spec-to-test-cases`, `superpowers:verification-before-completion` |

프로젝트 스택에 따라 추가 스킬을 매핑한다:

• Vue 프로젝트 → reviewer에 `vue-best-practices`, `vue-development-guides` 추가
• React 프로젝트 → reviewer에 `vercel-react-best-practices` 추가

Pipeline

Step 1: 프로젝트 디렉토리 준비

1. `.gitignore`에 `.agents`와 `.claude`가 포함되어 있는지 확인 2. 없으면 사용자에게 추가 여부 질문 3. 필요한 디렉토리 생성: `.agents/agents/`, `.claude/agents/`

1-2: 기존 에이전트 통합 스캔

`.claude/agents/`에 기존 에이전트 파일이 있으면 통합 흐름을 실행한다:

1. 기존 `.claude/agents/*.md` 파일 목록과 역할(name, description, tools) 추출 2. 역할 매핑: 기존 에이전트가 dev/reviewer/architect/tester 중 어떤 역할인지 판별 3. 충돌 감지 결과를 보여주고 사용자에게 선택:

기존 에이전트가 발견되었습니다:

  .claude/agents/my-dev.md       → 개발 역할 (Smith dev와 충돌)
  .claude/agents/my-reviewer.md  → 리뷰 역할 (Smith reviewer와 충돌)
  .claude/agents/api-agent.md    → 커스텀 역할 (충돌 없음)

> Smith 에이전트에 기존 규칙 병합 (기존 에이전트의 Must/Never를 Smith에 포함)
  Smith 에이전트로 교체 (기존 에이전트 → .claude/agents.bak/)
  공존 (기존 유지 + Smith는 {project}- 접두사로 분리)
  취소

| 선택 | 동작 | |------|------| | 병합 | 기존 에이전트의 Must/Never/Persona 분석 → `{project}-policy.md`에 반영 → 기존 파일 `.claude/agents.bak/`으로 백업 | | 교체 | 기존 파일 `.claude/agents.bak/`으로 백업 → Smith 에이전트로 대체 | | 공존 | 기존 파일 그대로 유지 → Smith 에이전트는 `{project}-` 접두사로 병존 | | 취소 | 아무것도 하지 않고 종료 |

기존 에이전트가 없으면 이 단계를 건너뛴다.

Step 2: 프로젝트 분석

**설정 파일 스캔:**

• `package.json` → 프레임워크, 런타임, 주요 의존성
• `tsconfig.json` / `jsconfig.json` → TypeScript 사용 여부
• `vite.config.*`, `next.config.*`, `nuxt.config.*` → 빌드 도구
• `pyproject.toml`, `go.mod`, `Cargo.toml` → 기타 언어

**프로젝트 구조 분석:**

• `src/` 구조 파악
• 기존 CLAUDE.md 읽기 → 컨벤션 수집
• 테스트 설정 파일 확인

**코드 패턴 샘플링:**

• 주요 디렉토리에서 2-3개 파일을 읽어 코딩 스타일 파악

Step 3: 에이전트 설계

3-1: base class 설계

**STATE class 자동 선택:**

`${CLAUDE_PLUGIN_ROOT}/plugins/smith/age