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 체인 재귀 해석:
   • 각 STATE class의 extends 필드를 따라 루트(state.md)까지 재귀적으로 올라간다
   • 각 레벨에서 Persona, Must, Never, Should, Override 섹션을 추출한다
2. 합산 규칙 (Union):
   • 모든 규칙은 합산된다 (union)
   • 동일 [Key]가 충돌할 때만 뒤쪽이 우선한다
   • Override 섹션의 규칙은 상속된 같은 Key를 대체한다
3. 우선순위 (낮음 → 높음):

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

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

Step 3: ACT 체인 컴파일

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

1. extends 체인 해석:
   • ACT class의 extends를 따라 루트(act.md)까지 올라간다
   • Trigger, Workflow, Verification, Output, Collaboration, Permission 섹션을 추출한다
2. 상속 규칙:
   • Workflow: 하위 class가 전체 재작성 (부분 override 아님)
   • Permission: 하위가 명시하면 대체, 미명시 시 상속
   • 나머지: 하위가 명시하면 대체, 미명시 시 상속

Step 4: 네이티브 frontmatter 매핑

Smith 필드를 Claude Code 네이티브 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 파일에서 핵심 규칙만 추출:
   • thinking-model.md → 불변 제약 5개 + GAVA 루프 요약 (~500자)
   • coding-standards.md → 핵심 원칙 표 + 금지 패턴 목록 (~800자)
4. 컴파일 출력의 본문에 ## Blueprint 섹션으로 삽입

축약 규칙:

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

## 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 빌트인 에이전트와 이름 충돌을 검증한다.

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

Step 6: 플랫 .md 파일 생성

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

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

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

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

Step 7: 보안 패턴 스캔

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

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

위험 패턴 목록:

스캔 방법:

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

결과 처리:

출력 예시:

빌드 중단:

🔍 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가 포함되는지
   • 누락 → WARN ("해당 축의 레포 특화 지식 없이 동작합니다. /code-forge:smith-create-agent --refresh 권장")

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

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

2. domain class 최소 규칙: Must에 엔티티 관련 규칙 1개 이상
   • 없음 → WARN ("도메인 분석이 미수행되었습니다")
3. policy class 최소 규칙: Must에 정책 관련 규칙 1개 이상
   • 없음 → WARN ("정책 분석이 미수행되었습니다")
4. context class 최소 규칙: Must에 구조 관련 규칙 1개 이상
   • 없음 → WARN ("컨텍스트 분석이 미수행되었습니다")
5. 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개 해석 완료 (순환 없음)
ACT 체인: 14개 해석 완료 (순환 없음)
이름 충돌: 1개 (explore → scout 자동 변환)
검증 결과: PASS

--regenerate 모드

기존 컴파일된 파일이 있을 때 수동 편집을 보존하며 재빌드한다.

1. 기존 agents/*.md 파일의 수동 편집 여부를 감지한다
   • .smith-build-manifest.json의 빌드 시간과 파일 수정 시간을 비교
2. 수동 편집된 파일은 건너뛰고 경고를 출력한다
3. 수동 편집되지 않은 파일만 재빌드한다

에러 처리