위키독스 분석 보드 — 2026-06-20

Claude Architect 자격증 취득을 위한 입문-중급 안내서로, Claude 생태계(API, Agent SDK, MCP, Claude Code)의 정석적 설계 패턴·안티패턴·시험 빈출 개념을 코드 예제와 함께 제시한다.

adopt 후보 3개(에러 taxonomy·.claude/rules/·WorkflowGate), improve 4개(tool_choice·툴 설명·컨텍스트 명시전달·범위 누락 방지), skip 1개(기초 개념) — 핵심 가치는 '이미 다 하고 있지만 정석적인 공식 패턴으로 정리되지 않아 ad-hoc하게 구현된 것들을 Anthropic 공식 설계 관행에 맞춰 체계화할 수 있는 청사진'이다. 자격증 시험 내용이라 깊이보다 폭이 넓고, 형님 시스템의 부족한 정량 평가·테스트 인프라·동시성 제어 같은 진짜 약점은 다루지 않는다.

1. ADOPT 구조화된 에러 응답 분류 체계 (transient/validation/business/permission)
   1) `~/.hermes/lib/error_taxonomy.py` 신규 생성: `ErrorCategory(transient/validation/business/permission)` enum + `StructuredError` dataclass 정의. 2) `harness_integration.py`의 retry 로직을 `isRetryable=True`일 때만 retry하도록 수정. 3) PostToolUse hook에서 MCP 툴 결과가 `isError=True`면 taxonomy에 따라 분기 처리하도록 `pre_write_harness_check.py`에 통합. 4) 텔레그램 알림 메시지에 errorCategory 포함.
2. ADOPT .claude/rules/ 조건부 규칙 (YAML frontmatter + glob 패턴)
   1) `.claude/rules/` 디렉토리 생성. 2) `python.yaml`: `paths: ["**/*.py"]` — type hints 필수·f-string 사용·SPoE 원칙·예외 구체화 규칙. 3) `markdown.yaml`: `paths: ["**/*.md"]` — 옵시디언 프론트매터 규칙·백링크 규칙·해라체 규칙. 4) `shell.yaml`: `paths: ["**/*.sh", "**/*.zsh"]` — 에러 핸들링·환경변수 검증 규칙. 5) CLAUDE.md에서 파일유형별 규칙을 제거하고 @import로 참조.
3. IMPROVE tool_choice를 통한 구조화된 출력 강제 (JSON 구문 오류 제거)
   1) `~/.hermes/lib/structured_response.py` 생성: `force_tool_call(client, tool_schema, messages)` 유틸리티 함수 → tool_choice='tool'로 호출하고 tool_use 블록만 반환. 2) agent_registry.py의 agent 검색 결과를 tool_use로 강제하여 검색 결과 구조 일관성 보장. 3) pipeline_observer.py의 상태 체크 결과도 동일 패턴 적용. 4) 기존 JSON 파싱 패턴을 단계적 마이그레이션.
4. IMPROVE 툴 설명(Description)의 상세화 규율 — 사용 시점·구분법·전제조건
   1) 각 MCP 서버의 툴 description을 7.1장 규율에 맞게 재작성: 사용 시점·입력 예시·반환 형식·유사 툴과의 구분·전제 조건 명시. 2) obsidian MCP의 search_note/get_note/create_note/update_note에 특히 구분 설명 보강. 3) `~/.hermes/scripts/tool_audit.py` 스크립트 작성 — 모든 MCP 툴의 description이 6개 요소를 포함하는지 자동 검사. 4) 툴 설명 변경 후 Claude가 올바른 툴을 선택하는지 regression test.
5. IMPROVE 서브에이전트 컨텍스트 미상속 — 명시적 전달 강제
   1) `~/.hermes/lib/context_builder.py` 생성: `build_subagent_context(task_type, coordinator_context)` 유틸리티 — task_type(blog/realestate/running 등)에 따라 필요한 컨텍스트 키를 강제하는 스키마 검증 포함. 2) kanban-orchestrator SKILL에 'Task 호출 전 context_builder 필수 사용' 규칙 추가. 3) debug-critic SKILL의 $ARGUMENTS 형식에 '컨텍스트 검증: 전달된 컨텍스트가 충분한가?' 검증 단계 추가.

VLA는 로봇이 '외워서 하는 것'에서 '이해하고 하는 것'으로 넘어가는 전환점이며, 그 핵심은 Vision·Language·Action을 하나의 토큰 시퀀스로 통합해 Transformer가 처리하게 하는 설계 원리다.

이 책의 핵심 도메인은 물리적 로보틱스고 형님 시스템은 순수 소프트웨어 자동화라서, 책의 70% (ViT·DINO·CLIP·Joint·DoF·IK·Transformer 내부구조)는 적용처가 전혀 없다. 그러나 나머지 30% — '토큰화를 설계 결정으로 보는 관점', 'Bottom-up+Top-down 학습 경로 설계', ''논문 읽기→실행' 브릿지의 Action Detokenizer 패턴' — 은 형님 시스템에 현재 완전히 부재하며 도입 시 SKILL 비대화 관리·온보딩·지식→자동화 전환율을 획기적으로 개선할 수 있다. adopt 후보 2개, improve 2개, skip 3개 — 핵심 가치는 '형님 시스템의 ad-hoc 성장을 설계 기반 성장으로 전환할 언어를 제공한다'는 점에 있다. 단, 이 책만으로는 안 되고 위에 명시한 concrete_action들을 실제로 구현해야 가치가 실현된다.

1. ADOPT 토큰화를 '설계 결정'으로 보는 관점 — vocabulary 크기·시퀀스 길이·일반화의 tradeoff를 동시에 고려하는 설계 사고
   신규 파일 `.hermes/docs/TOOL_VOCABULARY_DESIGN.md` 생성. MCP 툴·SKILL·agent를 '토큰 vocabulary'로 개념화하고, 각 항목 추가 시 (1)컨텍스트 예산 소비량 추정, (2)다른 항목과의 중복도, (3)일반화 가능성을 평가하는 체크리스트를 정의. agent_registry.py에 현재 vocabulary stats(총 SKILL 수, MCP 툴 수, 평균 SKILL.md 토큰 길이)를 출력하는 `--vocab-stats` 플래그 추가.
2. IMPROVE Bottom-up 기초 + Top-down 시스템 뷰를 결합한 구조적 학습 경로 설계
   기존 HANDOFF.md 상단에 `## 온보딩 경로` 섹션 추가. 3가지 프로필(①에이전트 개발 초보 → '기초 SKILL 5개 먼저', ②기존 모듈에 기능 추가하려는 개발자 → 'HARNESS_DOMAIN_REGISTRY.md 먼저', ③자동화 트러블슈팅 → 'launchd + cron + PostToolUse hook' 순서)로 읽기 경로 제시. 각 SKILL.md 상단에 '선행 학습 SKILL' 메타데이터 추가 검토.
3. ADOPT '논문 읽기'와 '실제 동작하는 시스템' 사이의 간극을 메우는 브릿지 설계 — Action Detokenizer 개념
   신규 모듈 `harness/action_detokenizer.py` 작성 — wikidocs 추출 결과를 입력받아 도메인별로 어떤 자동화 액션으로 변환할지 결정하는 라우터. 입력: (source=wikidocs, book_id, 추출텍스트, detected_domains[]) → 출력: (action_type, target_skill, execution_params). 기존 blog-naver, running-daily, realestate-analyzer에서 이미 동작 중인 '지식→액션' 변환 패턴을 추출해 템플릿화.
4. IMPROVE Vocabulary 예산 관리 — 시스템에 등록된 도구/스킬 개수와 컨텍스트 윈도우 소비의 관계를 정량화하는 개념
   신규 스크립트 `scripts/skill_vocabulary_audit.py` 작성. (1)각 SKILL.md의 토큰 길이 측정 (tiktoken), (2)지난 30일 간 skill_view() 호출 로그에서 발동 빈도 집계, (3) '토큰비용/발동빈도' 비율로 ROI 정렬, (4) 임계값 이하 SKILL은 '비활성화 제안' 리포트 출력. cron 주간 실행.