smith-build

Smith Build — Build-Time Compilation

프로젝트 에이전트 인스턴스(.agents/agents/*.md)를 정적 .md 파일로 컴파일한다.

비유: TypeScript → tsc → .js 와 같이, Smith 템플릿 → /code-forge:smith-build → 플랫 .md

플러그인 에이전트(agents/)는 직접 편집한다. Smith 빌드는 프로젝트 에이전트 전용.

References

• references/compilation-spec.md — STATE/ACT 컴파일 시맨틱 상세
• references/output-template.md — 출력 파일 템플릿

빌드 모드

/code-forge:smith-build --project        # 프로젝트 에이전트 빌드: .agents/agents/ → .claude/agents/
/code-forge:smith-build --validate       # 검증만, 출력 없음
/code-forge:smith-build --regenerate     # 수동 편집 보존하며 재빌드

Pipeline

Step 1: 소스 파일 수집

소스: ./.agents/agents/*.md (type: instance만)
출력: ./.claude/agents/

1. 소스 디렉토리의 모든 .md 파일을 읽는다
2. frontmatter에서 type: instance이고 agent-system: Smith인 파일만 필터링한다
3. 유효하지 않은 파일은 경고를 출력하고 건너뛴다

Step 2: STATE 체인 컴파일

각 인스턴스의 state 배열을 순서대로 해석한다.

1. extends 체인 재귀 해석:
2. 각 STATE class의 extends 필드를 따라 루트(state.md)까지 재귀적으로 올라간다
3. 각 레벨에서 Persona, Must, Never, Should, Override 섹션을 추출한다

1. 합산 규칙 (Union):
2. 모든 규칙은 합산된다 (union)
3. 동일 [Key]가 충돌할 때만 뒤쪽이 우선한다
4. Override 섹션의 규칙은 상속된 같은 Key를 대체한다

1. 우선순위 (낮음 → 높음):

`` state.md (추상) → extends 상위 → extends 하위 → state[] 앞 → state[] 뒤 → instance body ``

1. Persona 규칙: instance body의 Persona가 있으면 상속된 Persona를 대체한다

Step 3: ACT 체인 컴파일

인스턴스의 act 필드에서 ACT class를 해석한다.

1. extends 체인 해석:
2. ACT class의 extends를 따라 루트(act.md)까지 올라간다
3. Trigger, Workflow, Verification, Output, Collaboration, Permission 섹션을 추출한다

1. 상속 규칙:
2. Workflow: 하위 class가 전체 재작성 (부분 override 아님)
3. Permission: 하위가 명시하면 대체, 미명시 시 상속
4. 나머지: 하위가 명시하면 대체, 미명시 시 상속

Step 4: 네이티브 frontmatter 매핑

Smith 필드를 Claude Code 네이티브 frontmatter로 변환한다.

매핑 테이블:

| Smith 필드 | 네이티브 필드 | 소스 | |----------|-------------|------| | name | name | instance frontmatter | | description | description | instance frontmatter | | model | model | instance > ACT Permission > 기본값(sonnet) | | tools | tools | instance > ACT Permission > 기본값(Read, Grep, Glob) | | permissionMode | permissionMode | instance > ACT Permission > 기본값(bypassPermissions) | | maxTurns | maxTurns | instance frontmatter | | boundary | 본문에 포함 | instance frontmatter | | memory | memory | instance frontmatter (있을 경우) | | skills | skills | instance frontmatter (있을 경우) | | isolation | isolation | instance frontmatter (있을 경우) |

제거 필드 (컴파일 후 불필요):

• type, agent-system, schema, extends, state, act

disallowedTools 자동 계산:

• 전체 도구 목록: [Read, Write, Edit, Bash, Grep, Glob]
• tools에 없는 도구를 disallowedTools에 추가한다

Step 4.5: Blueprint 임베딩 (degraded mode 지원)

인스턴스의 STATE 체인에서 blueprint 필드가 발견되면, 참조된 규칙 파일의 핵심 축약본을 에이전트 본문에 인라인 임베딩한다.

처리 흐름:

1. STATE 체인의 모든 class를 순회하며 blueprint 필드를 수집한다
2. 중복 제거 (동일 경로는 1회만 처리)
3. 각 blueprint 파일에서 핵심 규칙만 추출:
4. thinking-model.md → 불변 제약 5개 + GAVA 루프 요약 (~500자)
5. coding-standards.md → 핵심 원칙 표 + 금지 패턴 목록 (~800자)
6. 컴파일 출력의 본문에 ## Blueprint 섹션으로 삽입

축약 규칙:

| 원본 파일 | 추출 대상 | 축약 크기 | |----------|----------|----------| | thinking-model.md | ## 불변 제약 섹션 전문 + ## 작업 루프 1줄 요약 | ~500자 | | coding-standards.md | ## 핵심 원칙 표 + ## 금지 패턴 목록 | ~800자 |

출력 예시 (에이전트 본문):

## Blueprint

> 플러그인 없이도 동작하는 핵심 규칙 (code-forge 사고모델 축약)

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

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

blueprint 필드가 없으면 이 단계를 건너뛴다.

이 섹션은 @${CLAUDE_PLUGIN_ROOT}/rules/... 참조를 대체하지 않는다. 플러그인이 로드된 상태에서는 alwaysApply 규칙이 전문을 적용하고, blueprint는 degraded mode 안전망이다.

Step 5: 이름 충돌 검증

Claude Code 빌트인 에이전트와 이름 충돌을 검증한다.

| 충돌 이름 | 변환 이름 | 이유 | |----------|----------|------| | explore | scout | Claude Code Explore 빌트인 에이전트와 충돌 |

프로젝트 에이전트(--project)는 {project}- 접두사를 사용하므로 충돌 가능성이 낮다.

Step 6: 플랫 .md 파일 생성

references/output-template.md의 템플릿에 따라 컴파일된 에이전트 파일을 생성한다.

instruction 참조 매핑 (4단계 권한 기준):

| 에이전트 단계 | 에이전트 | instruction 참조 | |-------------|---------|----------------| | READ-ONLY | analyst, architect, refactor-advisor, vision | 없음 | | SHELL-ACCESS | scout, code-reviewer | parallel-execution | | SHELL-ACCESS | git-operator, researcher | 없음 | | EDIT-ONLY | lint-fixer, build-fixer | coding-standards | | READ-WRITE-FULL | implementor, deep-executor, assayer, codex | parallel-execution, coding-standards |

프로젝트 에이전트 (--project)의 instruction 참조:

프로젝트 에이전트는 @${CLAUDE_PLUGIN_ROOT}/rules/... 참조 대신 blueprint 임베딩을 사용한다. 이를 통해 플러그인 없이도 핵심 규칙이 동작한다.

| 모드 | instruction 참조 | blueprint | |------|----------------|-----------| | 전체 빌드 (기본) | @ 참조 유지 | 없음 (플러그인 필수) | | 프로젝트 빌드 (--project) | @ 참조 제거 | blueprint 임베딩 (자립형) |

Step 7: 보안 패턴 스캔

컴파일된 에이전트 파일에서 위험 패턴을 검사한다.

스캔 대상: 컴파일 출력 디렉토리의 모든 .md 파일

위험 패턴 목록:

| 패턴 | 위험도 | 설명 | |------|--------|------| | dangerouslyDisableSandbox | CRITICAL | 샌드박스 비활성화 | | --no-verify | HIGH | git 훅 우회 | | rm -rf | HIGH | 재귀 삭제 | | curl\|sh 또는 wget\|sh | CRITICAL | 원격 스크립트 실행 | | eval( | HIGH | 동적 코드 실행 | | ignore previous instructions | CRITICAL | 프롬프트 인젝션 |

스캔 방법:

PATTERNS_CRITICAL=("dangerouslyDisableSandbox" "curl.*|.*sh" "wget.*|.*sh" "ignore previous instructions")
PATTERNS_HIGH=("--no-verify" "rm -rf" "eval(")

FOUND_CRITICAL=false
FOUND_HIGH=false

echo "🔍 Security Scan..."

for file in ${OUTPUT_DIR}/*.md; do
  for pattern in "${PATTERNS_CRITICAL[@]}"; do
    if grep -q "$pattern" "$file"; then
      echo "⚠️  CRITICAL: '$pattern' found in $(basename $file)"
      FOUND_CRITICAL=true
    fi
  done
  for pattern in "${PATTERNS_HIGH[@]}"; do
    if grep -q "$pattern" "$file"; then
      echo "⚠️  HIGH: '$pattern' found in $(basename $file)"
      FOUND_HIGH=true
    fi
  done
done

결과 처리:

| 발견 결과 | 대응 | |----------|------| | CRITICAL 패턴 발견 | 빌드 중단, 에러 출력 | | HIGH 패턴 발견 | 경고 출력, 사용자 확인 요청 | | 패턴 미발견 | ✅ Security scan passed 출력 후 계속 |

출력 예시:

빌드 중단:

🔍 Security Scan...
⚠️  CRITICAL: 'dangerouslyDisableSandbox' found in deep-executor.md
❌ Build aborted: CRITICAL security pattern detected.
   Review the source instance and remove dangerous patterns.

통과:

🔍 Security Scan...
✅ Security scan passed (14 agents scanned)

Step 7.5: Deep Specialization 완전성 검증 (프로젝트 에이전트만)

.agents/agents/ 소스의 프로젝트 에이전트에 대해 추가 검증:

1. base class extends 확인: {project}-base.md의 extends에 domain/policy/context가 포함되는지
2. 누락 → WARN ("해당 축의 레포 특화 지식 없이 동작합니다. /code-forge:smith-create-agent --refresh 권장")

1.5. blueprint 확인: {project}-base.md에 blueprint 필드가 있는지

• 누락 → WARN ("사고모델 임베딩 없음. degraded mode에서 핵심 규칙이 적용되지 않습니다")

1. domain class 최소 규칙: Must에 엔티티 관련 규칙 1개 이상
2. 없음 → WARN ("도메인 분석이 미수행되었습니다")

1. policy class 최소 규칙: Must에 정책 관련 규칙 1개 이상
2. 없음 → WARN ("정책 분석이 미수행되었습니다")

1. context class 최소 규칙: Must에 구조 관련 규칙 1개 이상
2. 없음 → WARN ("컨텍스트 분석이 미수행되었습니다")

1. Analysis Manifest staleness: .analysis-manifest.json 존재 시 30일 경과 → WARN

Step 8: 빌드 매니페스트 생성

.claude/agents/.smith-build-manifest.json에 빌드 메타데이터를 기록한다.

{
  "version": "2.0.0",
  "buildTime": "ISO 8601 타임스탬프",
  "source": ".agents/agents/",
  "agents": [
    {
      "name": "{project}-dev",
      "source": ".agents/agents/{project}-dev.md",
      "stateChain": ["{project}-base.md", "state/role/developer.md"],
      "actChain": ["act/act.md", "act/dev/implementor.md"],
      "model": "sonnet",
      "permissionMode": "bypassPermissions"
    }
  ]
}

--validate 모드

출력 파일을 생성하지 않고 검증만 수행한다.

검증 항목:

1. 모든 인스턴스 파일 파싱 가능
2. STATE 경로가 유효하고 extends 체인이 순환하지 않음
3. ACT 경로가 유효하고 extends 체인이 순환하지 않음
4. 이름 충돌 없음 (빌트인 + 인스턴스 간)
5. 필수 frontmatter 필드 존재 (type, name, agent-system, state, act)

출력:

✅ Smith Build Validation

인스턴스: 14개 파싱 완료
STATE 체인: 14개 해석 완료 (순환