harness-architect는 새 프로젝트에 필요한 CLAUDE.md, settings.json, rules, agents, skills, hooks, MCP 설정을 사람이 직접 구축하는 부담 없이 오케스트레이션해 만들어 주는 Claude Code 플러그인입니다. 단순 템플릿 복사가 아니라, 프로젝트를 스캔하고 인터뷰한 뒤 Red-team Advisor가 매 단계를 검토합니다.
대상 프로젝트 폴더를 주면, Claude Code가 그 프로젝트에 맞춰 동작하도록 필요한 설정·규칙·에이전트·자동화 훅을 생성합니다. 사용자는 Phase 전환 시점에만 개입합니다.
Fresh Setup / Cursor Migration / Harness Audit 세 가지 모드를 프로젝트 상태에 따라 자동 분기합니다. 생성 결과는 CLAUDE.md, .claude/settings.json, .claude/rules/, .claude/agents/, .claude/skills/, .claude/hooks/, MCP 선정까지 모든 레이어를 포함합니다.
파일 시스템을 직접 스캔하고 부족한 정보만 인터뷰로 질문합니다.
매 Phase 산출물을 독립 리뷰하고 BLOCK/ASK/NOTE로 분류합니다.
docs/{요청명}/ 폴더에 Phase별 산출물을 저장해, 세션이 끊겨도 마지막 완료 Phase 다음부터 이어서 진행합니다.
WHO(.claude/agents/)와 HOW(playbooks/)를 분리해 메인 세션의 Skill 툴 우회 실행을 원천 차단합니다. 외부 노출이 필요한 도메인 스킬만 .claude/skills/로 갑니다.
"Claude Code로 뭘 할지"는 프로젝트마다 다르지만, "하네스를 어떻게 구성해야 하는지"의 원칙은 반복됩니다. 그 반복 작업을 자동화해 프로젝트마다 균질한 하네스를 얻기 위해 만들었습니다.
새 프로젝트마다 CLAUDE.md 형식, 권한 범위, 훅 스크립트, 에이전트 구성을 처음부터 고민합니다. 개인·프로젝트마다 품질이 달라지고, 보안 기본값을 빠뜨리기 쉽습니다.
Phase 게이팅으로 결정 순서를 강제하고, AskUserQuestion으로 암묵적 가정을 막고, Advisor로 산출물 품질을 더블체크합니다. 결과는 어느 프로젝트에서든 동일한 구조로 읽히는 하네스입니다.
"이 툴 자신의 규칙"이 생성 결과에 새어나가지 않도록 체크리스트로 필터링합니다.
메인 세션은 Summary(~200단어)만 들고, 상세는 산출물 파일에 남기는 패턴으로 긴 세션에서도 안정적입니다.
언제 실행해도 동일한 9-Phase와 동일한 산출물 네이밍으로 편차를 줄입니다.
공식 Claude Code CLI가 설치되어 있고, 플러그인 시스템(/plugin)을 쓸 수 있는 최신 버전이면 충분합니다.
플러그인 명령어(/plugin)가 지원되는 최신 버전을 사용하세요. claude --version 으로 확인.
대상 프로젝트는 Git으로 관리되는 상태를 권장합니다. 산출물은 커밋 단위로 리뷰됩니다.
신규는 Fresh Setup, .cursor/가 있으면 Cursor Migration, 이미 .claude/가 있으면 Audit 모드로 자동 분기됩니다.
Claude Code가 인증된 상태여야 합니다. Anthropic 키/워크스페이스 설정은 .claude/settings.local.json(gitignored)에 저장하세요.
macOS · Linux · Windows(WSL 2) 모두 지원. Windows는 WSL 경로(/mnt/c/...) 사용을 권장.
긴 프로젝트는 Opus 계열 모델을 권장합니다. 9-Phase 전체가 한 세션에서 진행될 수 있도록 설정하세요.
세팅할 프로젝트 폴더로 이동해 Claude Code를 연 뒤, 아래 순서대로 입력합니다. 최초 1회는 마켓플레이스 등록이 필요합니다.
대상 프로젝트의 루트로 이동한 뒤 Claude Code를 시작합니다. 하네스가 이 위치에 만들어집니다.
# 터미널
cd path/to/your-project
claude플러그인 소스를 Claude Code에 알려 줍니다. 이미 등록했다면 건너뛰세요.
/plugin marketplace add leee880619-commits/ClaudeCode-Harness-Setup-Assistant마켓플레이스에서 harness-architect를 설치합니다.
/plugin install harness-architect@harness-architect-marketplace/harness-architect:harness-setup 커맨드가 로드됩니다./plugin update 로 TUI를 열어 Installed → harness-architect → Update now 를 선택하세요. /plugin update harness-architect 를 바로 쓰면 "already at the latest" 로 보일 수 있어 2단계 절차를 권장합니다.# 1) 마켓플레이스 캐시 새로고침
/plugin marketplace update harness-architect-marketplace
# 2) TUI 열고 Installed → harness-architect → Update now 선택
/plugin updatev0.9.0 부터 사용 흐름은 두 가지로 단순화됐습니다 — 신규 설치(harness-setup)와 기존 하네스 점검(audit). 개별 감사 3종은 고급 사용자용으로 계층화됐습니다.
주요 커맨드 2개 — 대부분의 사용자는 이 둘로 충분
harness-setup — 하네스 구축 (시나리오 A)
완전 신규 설치 자기완결 커맨드. 신규 프로젝트·Cursor 마이그레이션·기존 하네스 재진입을 대상 폴더 상태로 자동 분기합니다. v0.9.0부터 Phase 9 Runtime Spot Check가 강화됐습니다.
# 기본 — Phase 0에서 경로·프로젝트 정보를 질문으로 수집
/harness-architect:harness-setup
# 프로젝트 설명과 함께 — 구체적일수록 인터뷰가 짧아짐
/harness-architect:harness-setup 이 프로젝트는 Next.js + tRPC 내부 운영 대시보드야.
테스트는 Vitest, 배포는 Vercel. 솔로 개발이고, DB는 Supabase.
# 경로 인자 — Phase 0의 "경로 입력" 질문이 생략됨
/harness-architect:harness-setup /path/to/your/project
# "빠르게" 또는 --fast 포함 — Phase 2.5 도메인 리서치를 스킵
/harness-architect:harness-setup --fast /path/to/your/project.claude/가 있으면 Harness Audit 재진입 모드로, .cursor/가 있으면 Cursor Migration 모드로 자동 전환됩니다. 이미 작업 중이던 산출물이 있으면 재개 여부를 묻습니다.audit — 통합 사후 감사 (시나리오 B)
기존 하네스의 구성 정합성 · 런타임 부채 · 프로젝트 적합성 3축을 병렬 실행해 단일 통합 보고서로 반환합니다. Pre-flight 1회, auditor 3개 자동 소환, severity 통합 매핑(Critical/High/Medium/Low/Aligned), SSoT 충돌 시 ops-audit 우선·원본 등급 병기, 부분 실패 처리, 300 라인 상한 자동 축약, heuristic-only-mode 조건부 경고. read-only.
# 현재 폴더의 하네스를 통합 감사 (경로 질문으로 수집)
/harness-architect:audit
# 경로 인자로 직접 지정
/harness-architect:audit /path/to/existing/project개별 감사 커맨드 (고급 사용자용) — 특정 축만 단독으로 보고 싶을 때
harness-audit — 구성 정합성 단독 감사
v0.9.0 실체화 (이전엔 phantom 참조). 구성 정합성만 단독 감사합니다. 4-scope 스캔, JSON 유효성, anti-pattern, 권한, 에이전트↔플레이북 매핑을 검사해 CRITICAL/HIGH/MEDIUM/LOW 등급 리포트를 반환합니다.
/harness-architect:harness-audit
/harness-architect:harness-audit /path/to/existing/projectops-audit — 런타임 부채 단독 감사
완성된 하네스가 실제 운영 중 어디서 무너지는지 6개 Dimension(A–F: 세션 연속성·실패 복구·이중 관리·덮어쓰기·Jaccard 중복·라우팅 프로토콜)을 read-only로 점검합니다. v0.6.0부터 라우팅 프로토콜 검사가 포함됐습니다.
/harness-architect:ops-audit
/harness-architect:ops-audit /path/to/existing/projectfit-audit — 프로젝트 적합성 단독 감사
빌드 시점 전제(01-discovery-answers.md) vs 현재 프로젝트 실상의 드리프트를 7 Dimension으로 감사합니다. 트랙 드리프트, 아키타입/품질축 미스핏, 에이전트 규모 미스핏, 권한 경로 드리프트 + Security Warning, CLAUDE.md/도메인 정체성 드리프트, Baseline 부재 처리, MCP/훅 외부 인터페이스 드리프트. MAJOR-DRIFT-CRITICAL / MAJOR-DRIFT-MED / MINOR-DRIFT / ALIGN 4등급. read-only.
/harness-architect:fit-audit
/harness-architect:fit-audit /path/to/existing/projecthelp — 사용법 안내
커맨드 목록·9-Phase 흐름·재개 방법·생성 파일 트리를 정적으로 출력합니다. 에이전트를 소환하지 않습니다.
/harness-architect:help이후 Claude가 AskUserQuestion으로 묻는 항목에 답변만 하면 됩니다. Advisor가 BLOCK을 띄운 경우엔 수정 여부를 확인받습니다.
세션이 끊겨도 동일한 대상 프로젝트 폴더로 돌아와 플러그인을 다시 호출하면, docs/{요청명}/의 산출물 번호로 이전 작업을 감지해 "계속 / 새로 시작"을 묻습니다. 별도의 재개용 키워드는 필요 없습니다.
# 같은 프로젝트 폴더에서 다시 호출
/harness-architect:harness-setup
# 또는 이전 Claude Code 세션 자체를 복원
/resume각 Phase는 독립 서브에이전트가 담당합니다. 산출물은 docs/{요청명}/NN-*.md로 남고, 다음 Phase는 그 파일의 "Context for Next Phase" 섹션을 Read해 이어갑니다.
대상 프로젝트 경로 확정, 요청명 자동 생성, 기존 작업 감지 및 재개 여부 확인, docs/{요청명}/ 작업 폴더 생성. 프로젝트 이름·유형·팀 규모와 함께 기본 성능 수준(경제/균형/고성능)을 수집해 Phase 5 모델 배정의 힌트로 사용합니다.
fresh-setup / cursor-migration / harness-audit 중 자동 분기. CLAUDE.md, settings.json, rules 초안 생성. (여기의 harness-audit은 재진입 분기 모드 — 기존 하네스가 있는 프로젝트를 harness-setup으로 다시 실행하면 진입합니다. v0.9.0부터 독립 커맨드 /harness-architect:harness-audit도 별개로 제공됩니다.)
딥리서치·웹툰·유튜브·코드리뷰·기술문서·데이터 파이프라인·마케팅·프론트엔드 디자인 등 도메인이 특정되면, knowledge/domains/ 9종 KB와 WebSearch/WebFetch로 표준 워크플로우·역할·도구 스택을 수집. 출처 URL + 발췌일 강제.
프로젝트 목적에 맞는 작업 스텝 시퀀스를 정의. 각 스텝의 목적·트리거·완료 조건·의존성을 문서화.
각 스텝의 에이전트 실행 체인(파이프라인) 설계. 모델·쓰기 범위·소통 포인트를 결정. 생성·결정·설계·계획·리서치 파이프라인은 말단에 도메인 전문 레드팀 리뷰어를 필수 배치하고, BLOCK 3단 에스컬레이션 래더(자동 승인 → 사용자 결정 → 작업 중단)를 적용합니다.
Teams/Agent/SendMessage 기반 에이전트 구성, 소유권 테이블과 Orchestrator 패턴 결정. Phase 0에서 받은 기본 성능 수준(경제/균형/고성능) 힌트로 역할 복잡도 매트릭스에 따라 에이전트별 모델을 자동 배정합니다.
각 에이전트의 방법론(HOW)을 작성하면서 저장 위치를 2케이스로 분기 결정. 외부 노출이 필요한 도메인 스킬 → .claude/skills/(케이스 A), 에이전트 전용 방법론 → playbooks/(케이스 B). 동시에 allowed_dirs로 쓰기 범위를 확정합니다.
Phase 6 Advisor 통과 직후, 스킬이 다 드러난 시점에 에이전트 · 역할 · 사용 스킬 · 모델 · 상대 비용 힌트를 하나의 표로 묶어 최종 1회 승인받습니다. 전체 승인 / 개별 에이전트 조정 / 티어 일괄 변경 3선택. 에이전트 ≥ 2 일 때만 실행.
자동화 훅 설계/설치(PreToolUse 가드 등)와 MCP 서버 선정·설치. 생성 파일 범위 제한을 강제화.
문법 · 일관성 · 메타 누수 체크리스트로 전체 하네스를 검증하고 최종 리포트를 생성.
9-Phase 완료 후 대상 프로젝트에 남는 레이어입니다. 왼쪽 트리의 항목에 포인터를 올리거나 클릭하면 오른쪽에 설명이 고정됩니다.
your-project/ ├── CLAUDE.md # 프로젝트 정체성·지침(서밋, 200줄 이내) ├── .claude/ │ ├── settings.json # 권한·env·훅·MCP │ ├── settings.local.json # 로컬/시크릿(gitignored) │ ├── rules/ # 항상 적용 규칙 + path-scoped │ ├── agents/ # 에이전트 정의(WHO) │ ├── skills/ # 도메인 스킬 — 자동 디스커버리 대상 │ └── hooks/ # 자동화 스크립트 ├── playbooks/ # 에이전트 전용 HOW — 우회 실행 방지 ├── docs/{요청명}/ │ ├── 00-target-path.md # Phase 0 산출 │ ├── 01-discovery-answers.md # Phase 1–2 │ ├── 02b-domain-research.md # Phase 2.5 (옵션) │ ├── 02-workflow-design.md # Phase 3 │ ├── 03-pipeline-design.md # Phase 4 │ ├── 04-agent-team.md # Phase 5 │ ├── 05-skill-specs.md # Phase 6 │ ├── 06-hooks-mcp.md # Phase 7–8 │ └── 07-validation-report.md # Phase 9 └── .gitignore # settings.local.json 등 포함
프로젝트 정체성·기술 스택·개발 원칙·컨벤션을 200줄 이내로 요약. Claude가 세션 시작 시 자동 로딩.
허용/차단 권한(allow/deny), 환경변수, 훅, MCP 서버 등록. 깃에 커밋되는 공용 설정.
API 키나 개인 설정 등 시크릿은 여기에만. .gitignore로 커밋 금지.
항상 적용되거나 특정 경로에서만 적용되는 규칙 파일. meta-leakage-guard 등 품질 가드 포함.
각 Phase·역할을 맡는 서브에이전트의 정체성(WHO). 소환 시 자동 로딩되는 경량 정의.
Claude Code가 자동 디스커버리해 메인 세션에 노출되는 도메인 스킬 전용. 실제로 Skill 툴로 호출해도 되는 기능 단위만 이 경로에 둡니다. 에이전트 전용 방법론(HOW)은 여기가 아니라 playbooks/에 배치합니다.
PreToolUse/PostToolUse 등 이벤트 훅 스크립트. ownership-guard 등으로 범위 이탈을 차단.
서브에이전트가 Read해 실행하는 에이전트 전용 방법론(HOW). 자동 디스커버리 대상이 아니므로 메인 세션이 Skill 툴로 가로챌 수 없고, 반드시 에이전트 소환을 거쳐야 참조됩니다. 기존 프로젝트에 같은 이름 폴더가 없으면 새로 생성됩니다.
Phase별 산출물. 중단/재개 시 이 폴더의 번호를 기준으로 마지막 완료 Phase를 파악.
프로젝트 스코프 하네스의 루트. 프로젝트 기여자가 동일한 Claude Code 환경을 공유하기 위한 공통 설정 묶음.
최소한 .claude/settings.local.json, CLAUDE.local.md는 포함시켜 시크릿 유출을 방지.
실제로 자주 밟는 부분만 모았습니다.
API 키 · 토큰 · 개인 경로는 settings.local.json에만. 플러그인도 이 원칙을 감지해 경고합니다.
그냥 넘기지 말고, 오케스트레이터가 묻는 확인을 통해 해당 Phase를 피드백과 함께 재실행하세요. 최대 2회 루프가 설계돼 있습니다.
명시적으로 답하거나 "모르겠어요"를 선택하세요. 후자는 # TODO:로 표시되어 추후 보완됩니다.
초과 시 규칙 파일로 분리됩니다. 프로젝트 컨벤션·도메인 지식은 rules/로 이관해 관리하세요.
에이전트 파이프라인 프로젝트로 감지되면 Phase 3–5 통합 실행 옵션이 뜹니다. 시간을 크게 단축할 수 있습니다.
딥리서치·웹툰 제작·유튜브 기획·코드리뷰·기술문서·데이터 파이프라인·마케팅 캠페인 등 업계 표준이 있는 도메인이면 phase-domain-research가 큐레이션 KB와 라이브 검색으로 표준 워크플로우·역할·도구 스택을 모아 후속 Phase에 주입합니다. 필요 없으면 "해당 없음" 또는 "빠르게"로 자동 스킵.
8개 기준(솔로, 웹앱/CLI, 비에이전트, 소스 파일 ≤100개 등)을 모두 충족하면 Phase 3–6을 단일 에이전트가 25–35분에 처리합니다. 단, 세션 중단 시 재개 불가 — 처음부터 재실행이 필요합니다.
React/Vue/Svelte + Tailwind 등 UI 프레임워크가 감지되면 frontend-designer(생성) + frontend-ux-reviewer(리뷰) 에이전트 페어와 OKLCH·APCA Lc≥60·WCAG AA 색상 규칙이 내장된 스킬이 하네스에 자동 추가됩니다. 외부 스킬 추가 설치 없이 동작합니다.
/harness-architect:audit으로 통합 감사하세요/harness-architect:audit 한 번으로 3개 축을 병렬 감사: 구성 정합성(harness-audit) + 런타임 부채(ops-audit, 6 Dimension) + 프로젝트 적합성(fit-audit, 7 Dimension). 단일 통합 보고서로 Critical/High/Medium/Low/Aligned 통합 severity를 제공합니다. 특정 축만 단독으로 보려면 /harness-architect:harness-audit · ops-audit · fit-audit를 개별 호출하세요. 파일 수정 없이 read-only로 실행됩니다.
docs/{요청명}/도 함께 커밋하면 이후에 의사결정 히스토리를 그대로 되짚을 수 있습니다.