Smith Create Agent

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

호출 경로

위임 감지 방법: .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)은 보호.

추가 에이전트 예시

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

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

역할별 기본 ACT 매핑

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

기본 스킬 매핑

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

• 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}- 접두사로 분리)
  취소

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

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를 자동 선택한다:

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 [Perm