smith-create-agent

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/agents/state/ 에서 프로젝트 스택에 맞는 STATE class를 자동 선택한다:

감지 결과	STATE class
React	${CLAUDE_PLUGIN_ROOT}/plugins/smith/agents/state/framework/react.md
Next.js	${CLAUDE_PLUGIN_ROOT}/plugins/smith/agents/state/framework/next.md
Vue	${CLAUDE_PLUGIN_ROOT}/plugins/smith/agents/state/framework/vue.md
TypeScript	${CLAUDE_PLUGIN_ROOT}/plugins/smith/agents/state/language/typescript.md
JavaScript	${CLAUDE_PLUGIN_ROOT}/plugins/smith/agents/state/language/javascript.md
Python	${CLAUDE_PLUGIN_ROOT}/plugins/smith/agents/state/language/python.md
Django	${CLAUDE_PLUGIN_ROOT}/plugins/smith/agents/state/framework/django.md
Fastify	${CLAUDE_PLUGIN_ROOT}/plugins/smith/agents/state/framework/fastify.md
PostgreSQL	${CLAUDE_PLUGIN_ROOT}/plugins/smith/agents/state/database/postgresql.md
Redis	${CLAUDE_PLUGIN_ROOT}/plugins/smith/agents/state/database/redis.md
monorepo (workspaces)	${CLAUDE_PLUGIN_ROOT}/plugins/smith/agents/state/technique/monorepo.md
SSR 감지	${CLAUDE_PLUGIN_ROOT}/plugins/smith/agents/state/technique/ssr.md
testing-library 감지	${CLAUDE_PLUGIN_ROOT}/plugins/smith/agents/state/technique/testing-library.md

base class 파일 형식:

---
type: class
name: {project}-base
schema: ${CLAUDE_PLUGIN_ROOT}/plugins/smith/agents/interface/state-agent.md
extends:
  - ${CLAUDE_PLUGIN_ROOT}/plugins/smith/agents/state/framework/{framework}.md
  - ${CLAUDE_PLUGIN_ROOT}/plugins/smith/agents/state/language/{language}.md
blueprint:
  - ${CLAUDE_PLUGIN_ROOT}/rules/thinking-model.md
  - ${CLAUDE_PLUGIN_ROOT}/rules/coding-standards.md
---

## Persona
- [Identity] {프로젝트}의 전문가

## Must
- [Key] 프로젝트 공통 규칙 (분석에서 발견한 컨벤션)

## Never
- [Key] 프로젝트 공통 금지사항

blueprint 필드: 컴파일 시 축약본이 에이전트 본문에 인라인 임베딩된다. extends/state와 달리 STATE 체인에 합산되지 않고, 독립된 ## Blueprint 섹션으로 출력된다. 이를 통해 플러그인 없이도(degraded mode) 사고모델 핵심이 에이전트에 포함된다.

규칙 작성 원칙:

• 부모 STATE에 이미 있는 규칙은 반복하지 않는다
• 프로젝트에 특화된 규칙만 추가한다
• 부모 규칙을 바꿔야 하면 Override 섹션 사용

3-2: instance 에이전트 설계

instance 파일 형식:

---
type: instance
name: {project}-{role}
description: {역할 설명}
model: {ACT class [Model]에서 추출}
permissionMode: {ACT class [PermissionMode]에서 추출}
tools: {ACT class [Tools]에서 추출}
boundary: [{행동 범위}]
state:
  - ./.agents/agents/{project}-base.md
  - ${CLAUDE_PLUGIN_ROOT}/plugins/smith/agents/state/role/{role-state}.md
act: ${CLAUDE_PLUGIN_ROOT}/plugins/smith/agents/act/{category}/{act-class}.md
memory: project
skills:
  - {역할별 스킬 목록}
---

## Persona
- [Identity] {구체적 역할과 입출력}
- [Mindset] {판단 기준과 우선순위}
- [Communication] {출력 형식과 소통 스타일}

## Must
- [Key] 역할 특화 필수 규칙 (5~8개)

## Never
- [Key] 역할 특화 금지사항 (3~4개)

## Should
- [Key] 역할 특화 권장사항 (2~4개)

역할별 state 매핑:

역할	state에 포함할 role STATE
architect	${CLAUDE_PLUGIN_ROOT}/plugins/smith/agents/state/role/architect.md
dev	${CLAUDE_PLUGIN_ROOT}/plugins/smith/agents/state/role/developer.md (+ ${CLAUDE_PLUGIN_ROOT}/plugins/smith/agents/state/role/fe.md 또는 ${CLAUDE_PLUGIN_ROOT}/plugins/smith/agents/state/role/be.md)
reviewer	${CLAUDE_PLUGIN_ROOT}/plugins/smith/agents/state/role/quality.md
tester	${CLAUDE_PLUGIN_ROOT}/plugins/smith/agents/state/role/quality.md

3-3: 사용자 확인

설계 결과를 보여주고 확인받는다.

Step 4: 에이전트 파일 생성

1. .agents/agents/에 모든 에이전트 파일 작성 (base 1 + instance N)

Step 5: 빌드타임 컴파일

/code-forge:smith-build --project 를 실행하여 .agents/agents/의 Smith 인스턴스를 .claude/agents/에 컴파일한다.

1. .agents/agents/의 type: instance 파일을 대상으로 Smith 빌드 수행
2. STATE 체인 해석 → ACT 체인 해석 → 네이티브 frontmatter 매핑
3. .claude/agents/에 플랫 .md 파일 생성
4. 빌드 결과를 사용자에게 보고

Step 6: 후속 안내

• 생성된 파일 목록
• 컴파일된 에이전트가 .claude/agents/에 위치하여 즉시 사용 가능
• 규칙 수정 → .agents/agents/{project}-*.md 직접 편집 후 /code-forge:smith-build --project 재실행
• 역할 추가 → /code-forge:smith-create-agent {역할} 으로 추가 생성

기존 에이전트 수정

.agents/agents/에 에이전트가 이미 있으면:

1. 기존 에이전트 목록을 보여준다
2. "새로 만들기" vs "기존 수정" 중 선택
3. 수정 선택 시: 기존 파일 읽기 → 프로젝트 재분석 → 변경 필요 부분만 제안

역할별 규칙 가이드

architect (분석/설계)

Must:

• [ImpactAnalysis] 변경 시 영향 범위를 파일/컴포넌트 단위로 명세
• [Specification] 원본(Jira/Confluence/Figma)을 참조하여 명세서 작성
• [DataFlow] API 요청/응답 타입, 쿼리 키, 상태 변환 흐름을 명세에 포함
• [FileList] 생성/수정/삭제할 파일 목록과 변경 사유 기술
• [TestScenario] 검증해야 할 테스트 시나리오 함께 도출

Never:

• [NoImplBeforeReview] 명세서 리뷰 완료 전 구현 코드 작성 금지
• [NoAssumption] 기존 코드 실제 확인 없이 동작 가정 금지

Should:

• [AlternativeDesign] 구현 방식 대안과 트레이드오프 비교

dev (개발/구현)

Must:

• [SpecFirst] 확정된 명세서 확인 후 구현
• [TypeSafety] 새로운 API 응답/props/상태에 TypeScript 타입 정의 필수
• [ErrorHandling] API 실패, 빈 데이터, 로딩 상태 처리
• [ExistingPattern] 기존 패턴 확인 후 일관성 유지

Never:

• [NoSpecNoCode] 명세서 없이 구현 시작 금지
• [NoAnyType] any 타입 사용 금지
• [NoScopeCreep] 명세서에 없는 기능 추가 금지

reviewer (코드 리뷰)

Must:

• [SpecCompliance] 명세서 요구사항 전체 구현 여부 대조
• [ProjectConvention] 프로젝트 컨벤션 준수 검증
• [TypeReview] 타입 정의 정확성 검증

Never:

• [NoDirectFix] 코드 직접 수정 금지. 피드백만 제공
• [NoStyleNit] ESLint/Prettier로 잡히는 이슈에 시간 소비 금지

피드백 형식: [BLOCKER], [MAJOR], [MINOR], [SUGGESTION]

tester (테스트)

Must:

• [ScenarioFirst] 테스트 시나리오 먼저 도출
• [HappyPath] 정상 동작 시나리오 커버
• [EdgeCase] 빈 데이터, null, 경계값 커버
• [ErrorCase] API 실패, 유효성 검증 실패 커버

Never:

• [NoImplDetail] 내부 구현에 의존하는 테스트 금지
• [NoFlaky] 타이밍 의존 불안정 테스트 금지

테스트 시나리오 형식: Given-When-Then