Claude Code 하네스 완전 정리: CLAUDE.md·훅·서브에이전트와 하네스 10선

Claude Code나 Cursor 같은 터미널 기반 AI 코딩 에이전트를 쓰다 보면 필요 이상으로 비대한 코드를 뱉어내거나, 구조가 조금만 복잡해져도 엉뚱한 설계를 들고 오는 경우를 자주 만나게 됩니다. 에이전트가 내놓는 결과물의 품질은 모델 자체보다, 그 모델을 어떤 규칙과 실행 환경으로 감싸서 돌리느냐에 크게 좌우됩니다. 이렇게 에이전트의 행동을 제어하는 규칙·스킬·훅·연동 설정 묶음을 흔히 하네스(Harness)라고 부릅니다.

처음 이 글을 쓸 때는 CLI 한 줄로 설치하는 하네스 10가지를 소개하는 데 집중했습니다. 그런데 남이 만든 하네스를 설치해 놓고도 “이게 지금 어디에 무엇을 넣었고, 왜 가끔 안 먹히는지”를 모르면 오래 못 갑니다. 그래서 2026년 10월에 글을 다시 쓰면서, 하네스가 실제로 올라타는 Claude Code의 다섯 가지 확장 지점(CLAUDE.md, 설정과 권한, 훅, 스킬, 서브에이전트)을 공식 문서 기준으로 먼저 정리하고, 그다음에 하네스 10종과 조합법을 다뤘습니다. 하네스별 설명은 각 저장소의 README와 Weft 카탈로그 설명을 다시 확인해 고쳤고, 근거를 찾지 못한 수치는 뺐습니다.

하네스란? AI 에이전트가 임의로 행동하지 않고 규칙과 절차에 따라 작동하도록 감싸는 지침서와 실행 설정의 묶음입니다. Claude Code 기준으로는 CLAUDE.md, .claude/settings.json, 훅, 스킬, 서브에이전트, MCP 서버가 그 재료입니다.
설치 방법: 하네스 패키지 매니저 Weft를 쓰면 npm install -g @weft-ai/weft 후 weft install [이름] 한 줄로 설치하고, weft uninstall로 정확히 되돌릴 수 있습니다.
어떤 사람에게 필요한가: 코드 과잉 생성, 세션이 바뀔 때마다 맥락이 날아가는 문제, 작업 순서가 무너지는 문제를 겪고 있는 개발자. 그리고 그 원인을 설정 파일 수준에서 이해하고 싶은 사람.

하네스와 Weft란 무엇인가

개발 분야에서 하네스(Harness)는 원래 테스트 하네스처럼 특정 코드가 안정적으로 돌아가도록 감싸는 장치를 가리키는 말입니다. AI 에이전트 관점으로 옮기면, 모델이 코드를 읽고 고치고 테스트하는 과정에 씌우는 도구 권한, 프로젝트 규칙, 반복 작업 절차, 자동 실행되는 검사 스크립트의 모음이라고 정의할 수 있습니다.

이런 하네스를 터미널에서 패키지처럼 찾고 설치하고 지울 수 있게 해 주는 오픈소스 도구가 위프트(Weft)입니다. Weft 공식 저장소는 스스로를 “AI 코딩 에이전트용 Homebrew”라고 소개합니다. 하나의 카탈로그로 Claude Code, Codex, Gemini, Cursor, opencode를 모두 대상으로 삼고, 설치할 때 어느 CLI에 넣을지와 전역/프로젝트 범위를 묻습니다. 눈여겨볼 부분은 설치 방식입니다. 각 하네스의 설치 스크립트를 내 컴퓨터에서 돌리지 않고, Weft 레지스트리 쪽 CI가 샌드박스에서 미리 만들어 둔 결과물만 내려받아 배치합니다. 무엇을 어디에 썼는지는 ~/.weft/ 아래 영수증(receipt)으로 남기기 때문에 제거와 업그레이드가 정확합니다. 자체 설치 스크립트를 꼭 돌려야 하는 하네스는 따로 표시되고, 동의를 받거나 --trust를 명시해야 실행됩니다. Node 22 이상이 필요합니다.

# 설치
npm install -g @weft-ai/weft

# 찾기와 정보 보기
weft search planner
weft info gsd-core

# 설치 (대화형으로 CLI와 범위를 물음)
weft install gsd-core

# 스크립트용: CLI·범위 지정, 미리보기
weft install gsd-core --cli claude-code --scope local --yes
weft install gsd-core --dry-run

# 확인, 업그레이드, 제거
weft list
weft upgrade gsd-core
weft uninstall gsd-core

처음 글에서 함께 소개했던 dioptx/weft는 이름만 같은 별개 프로젝트입니다. 이쪽은 Claude Code 플러그인 형태의 워크플로 추적 도구로, 훅으로 작업 단계 순서를 강제하는 방식이라 아래 훅 설명과 함께 보면 참고가 됩니다. 패키지 매니저 Weft의 저장소는 goyoon2/weft입니다.

먼저 알아 둘 Claude Code의 다섯 가지 확장 지점

하네스를 설치하면 결국 아래 다섯 곳 중 어딘가에 파일이 생깁니다. 저는 새 하네스를 넣기 전에 이 표를 기준으로 “이건 지침인가, 강제인가”부터 구분합니다. 이 구분을 놓치면 규칙을 써 뒀는데 왜 안 지키냐는 같은 불만을 계속 반복하게 됩니다.

확장 지점	위치	성격	언제 쓰나
CLAUDE.md	`./CLAUDE.md`, `~/.claude/CLAUDE.md`, `.claude/rules/`	지침(맥락)	빌드 명령, 코딩 규칙, 폴더 구조처럼 매 세션 알아야 할 사실
설정·권한	`.claude/settings.json`, `settings.local.json`	강제	허용·거부할 도구와 명령, 환경 변수, 훅 등록
훅	설정 파일의 `hooks` 항목	강제(스크립트)	특정 시점에 반드시 실행돼야 하는 검사·포맷·차단
스킬	`.claude/skills/<이름>/SKILL.md`	절차(필요할 때 로드)	여러 단계로 된 반복 작업, 특정 상황에서만 필요한 지식
서브에이전트	`.claude/agents/<이름>.md`	역할 분리	리뷰, 조사처럼 별도 맥락과 제한된 도구로 돌리고 싶은 일

1. CLAUDE.md: 매 세션 읽는 지침서

Claude Code 메모리 문서는 CLAUDE.md를 “강제되는 설정이 아니라 맥락”으로 다룬다고 분명히 적어 둡니다. 모델이 판단에 참고할 뿐, 무조건 따르게 만드는 장치가 아니라는 뜻입니다. 그래서 문서는 무언가를 확실히 막고 싶다면 CLAUDE.md 대신 PreToolUse 훅을 쓰라고 권합니다. 하네스가 CLAUDE.md에 규칙을 잔뜩 넣었는데 가끔 무시된다면, 대부분 이 성격 차이 때문입니다.

문서에 나온 실용적인 지침을 몇 가지 추리면 이렇습니다.

위치와 범위: 팀이 공유할 규칙은 ./CLAUDE.md(또는 ./.claude/CLAUDE.md), 나만 쓰는 전역 취향은 ~/.claude/CLAUDE.md, 이 프로젝트에서 나만 쓸 설정은 ./CLAUDE.local.md에 두고 .gitignore에 넣습니다.
길이: 파일 하나당 200줄 이하를 목표로 하라고 권합니다. 길수록 맥락을 많이 먹고 지켜지는 정도가 떨어진다는 이유입니다.
경로별 규칙: 일부 폴더에만 해당하는 규칙은 .claude/rules/ 아래 파일로 빼고, 맨 위에 paths를 적으면 해당 파일을 다룰 때만 불러옵니다.
가져오기: @README, @package.json처럼 @경로로 다른 파일을 끌어올 수 있습니다. 백틱으로 감싸면 가져오지 않고 글자 그대로 남습니다.
시작점: /init을 실행하면 코드베이스를 분석해 빌드 명령과 테스트 방법을 담은 초안을 만들어 줍니다. 이미 파일이 있으면 덮어쓰지 않고 개선안을 제안합니다.
모순 정리: 두 지침이 서로 충돌하면 어느 쪽을 따를지 임의로 고를 수 있으니, 하네스를 여러 개 겹쳐 설치했다면 규칙끼리 부딪히는 곳이 없는지 주기적으로 봐야 합니다.

경로별 규칙 파일은 이런 모양입니다.

---
paths:
  - "src/api/**/*.ts"
---

# API 작성 규칙
- 모든 엔드포인트는 입력 검증을 거친다
- 에러 응답은 공통 포맷을 쓴다

참고로 Claude Code는 저장소에 AGENTS.md만 있는 경우 그것을 프로젝트 지침으로 읽을 수도 있습니다. 여러 에이전트를 함께 쓰는 팀이라면 공통 규칙은 AGENTS.md에 두고 CLAUDE.md에서 가져오는 구성이 관리하기 편합니다.

2. settings.json과 권한 규칙: 실제로 막는 곳

지침이 아니라 강제가 필요한 것은 설정 파일로 갑니다. 공식 설정 문서 기준으로 우선순위는 높은 쪽부터 관리자 설정, 명령줄 인자, 프로젝트 로컬(.claude/settings.local.json), 공유 프로젝트(.claude/settings.json), 사용자(~/.claude/settings.json) 순서입니다. 팀이 함께 쓸 권한과 훅은 .claude/settings.json에 넣어 커밋하고, 개인 예외는 settings.local.json에 둡니다. 설정 파일은 엄격한 JSON이라 주석이나 끝 쉼표가 있으면 오류가 납니다.

권한 규칙에서 꼭 기억할 것은 평가 순서입니다. 권한 문서에 따르면 규칙은 deny, ask, allow 순서로 확인하고 처음 걸리는 것이 결과를 정합니다. 더 구체적인 allow 규칙을 써도 넓은 deny 규칙을 뚫지 못하고, 사용자 설정에서 허용한 것도 프로젝트 설정에서 거부하면 막힙니다.

{
  "$schema": "https://json.schemastore.org/claude-code-settings.json",
  "permissions": {
    "allow": [
      "Bash(npm run *)",
      "Bash(git status)",
      "Bash(git diff *)"
    ],
    "deny": [
      "Read(./.env)",
      "Read(./secrets/**)",
      "Bash(git push *)"
    ]
  }
}

이 정도만 넣어 둬도 에이전트가 테스트와 빌드는 묻지 않고 돌리되, 비밀 값 파일을 읽거나 원격에 밀어 넣는 일은 못 하게 됩니다. 하네스가 이 파일을 건드리는지 확인하는 습관도 필요합니다. Weft는 설정 조각을 기존 JSON에 병합하고 영수증에 남기니, 설치 후 git diff .claude/로 무엇이 바뀌었는지 보는 것이 가장 빠릅니다.

3. 훅: 정해진 순간에 반드시 실행되는 스크립트

훅은 세션 시작(SessionStart), 프롬프트 제출(UserPromptSubmit), 도구 실행 직전(PreToolUse)과 직후(PostToolUse), 응답 종료(Stop), 서브에이전트 종료(SubagentStop), 맥락 압축 직전(PreCompact) 같은 시점에 셸 명령을 실행합니다. 훅 레퍼런스의 대표 예시는 rm -rf가 들어간 Bash 명령을 막는 PreToolUse 훅입니다.

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "if": "Bash(rm *)",
            "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/block-rm.sh"
          }
        ]
      }
    ]
  }
}

#!/bin/bash
# .claude/hooks/block-rm.sh  (chmod +x 필요, jq 사용)
COMMAND=$(jq -r '.tool_input.command')

if echo "$COMMAND" | grep -q 'rm -rf'; then
  jq -n '{
    hookSpecificOutput: {
      hookEventName: "PreToolUse",
      permissionDecision: "deny",
      permissionDecisionReason: "훅이 위험 명령을 막았습니다"
    }
  }'
else
  exit 0
fi

훅은 표준 입력으로 JSON을 받습니다. 파일 도구(Write, Edit, Read)라면 tool_input.file_path에 절대 경로가 들어 있어서, PostToolUse에 "matcher": "Edit|Write"를 걸고 방금 고친 파일에만 포매터나 린터를 돌리는 식으로도 많이 씁니다. 종료 코드 2로 끝나는 PreToolUse 훅은 허용 규칙보다 먼저 도구 호출을 멈춥니다. 반대로 훅이 “허용”을 돌려줘도 deny 규칙은 그대로 적용됩니다. 즉 훅과 권한 규칙은 서로를 우회하지 못하고, 둘 다 통과해야 실행됩니다.

하네스 관점에서 훅이 중요한 이유는 “규칙을 강제로 만드는 유일한 방법”이기 때문입니다. 아래에서 소개할 ponytail이 세션 시작 훅으로 규칙을 매번 다시 불러오고, dioptx/weft가 PreToolUse와 Stop 훅으로 작업 순서를 지키게 만드는 것도 같은 원리입니다. 남이 만든 훅은 내 권한으로 셸 명령을 실행한다는 점도 잊으면 안 됩니다. 설치 전에 스크립트 내용을 한 번은 열어 보는 것을 원칙으로 삼는 편이 좋습니다.

4. 스킬: 필요할 때만 불러오는 절차서

공식 스킬 문서에 따르면 스킬은 .claude/skills/<이름>/SKILL.md(프로젝트)나 ~/.claude/skills/<이름>/SKILL.md(개인)에 두는 마크다운 파일입니다. 위쪽 frontmatter의 description을 보고 Claude가 관련 있을 때 스스로 불러오고, 사용자는 /이름으로 직접 부를 수 있습니다. 예전의 .claude/commands/ 커스텀 명령은 스킬로 합쳐졌고, 기존 파일도 계속 동작합니다. 자동 호출을 막고 사람이 부를 때만 쓰게 하려면 disable-model-invocation: true를 넣습니다.

---
name: release-notes
description: 마지막 태그 이후 커밋을 읽고 릴리스 노트 초안을 만든다. 사용자가 릴리스 노트나 변경 요약을 요청할 때 사용.
disable-model-invocation: true
---

1. git describe --tags --abbrev=0 으로 마지막 태그를 찾는다
2. 그 이후 커밋을 기능/수정/기타로 나눈다
3. 사용자에게 보이는 변화만 한국어로 정리한다

메모리 문서도 여러 단계로 된 절차나 코드베이스 일부에만 해당하는 내용은 CLAUDE.md가 아니라 스킬이나 경로별 규칙으로 옮기라고 권합니다. 하네스 대부분이 스킬 묶음 형태인 이유가 여기에 있습니다. 평소에는 이름과 설명만 보이고 본문은 필요할 때만 불러오니, CLAUDE.md를 비대하게 만들지 않고도 지식을 많이 실어 둘 수 있습니다.

5. 서브에이전트: 맥락과 권한을 나눠 맡기기

서브에이전트 문서는 각 서브에이전트가 자기만의 맥락 창, 별도 시스템 프롬프트, 지정된 도구 권한으로 돈다고 설명합니다. 긴 조사나 코드 리뷰를 맡기면 메인 대화의 맥락이 덜 더러워지고, 리뷰어에게는 읽기 도구만 주는 식으로 권한을 좁힐 수 있습니다. 다만 서브에이전트가 보내는 요청도 같은 사용량 한도에서 차감됩니다.

---
name: code-reviewer
description: 변경된 코드의 품질과 보안 문제를 검토한다. 커밋 전에 사용.
tools: Read, Glob, Grep
model: sonnet
---

너는 이 저장소의 리뷰어다. 수정하지 말고 문제와 근거만 목록으로 보고한다.

프로젝트용은 .claude/agents/에, 모든 프로젝트용은 ~/.claude/agents/에 둡니다. 플러그인으로 들어온 서브에이전트는 보안상 hooks, mcpServers, permissionMode 항목이 무시된다는 점도 알아 두면, 하네스가 기대대로 안 움직일 때 원인을 찾기 쉽습니다.

10가지 하네스 한눈에 비교

이제 Weft 카탈로그에 있는 하네스 10가지를 보겠습니다. 설명은 2026년 10월 기준 각 원본 저장소와 Weft 카탈로그 설명을 바탕으로 정리했습니다.

도구명	원본 저장소	주요 해결 과제 및 강점
ponytail	DietrichGebert/ponytail	가장 단순한 해법 강제(YAGNI, 표준 라이브러리 우선), 세션 시작 훅으로 매번 자동 로드
anthropic-skills	anthropics/skills	Anthropic 공식 예제 스킬: 문서 처리, MCP 서버 제작, 스킬 작성, 웹 디자인
planning-with-files	OthmanAdi/planning-with-files	파일 기반 계획: `task_plan.md`·`findings.md`·`progress.md`로 맥락 유실 대비
gsd-core	open-gsd/gsd-core	명세 주도 개발 시스템(에이전트·스킬·명령·훅 일체)
mattpocock-skills	mattpocock/skills	TDD, 버그 진단, 도메인 모델링, PRD·이슈 작성 스킬
obsidian-skills	kepano/obsidian-skills	Obsidian 마크다운·Bases·JSON Canvas 편집, Obsidian CLI 연동
vercel-agent-skills	vercel-labs/agent-skills	Next.js·React 모범 사례, 뷰 트랜지션, React Native, Vercel 배포
gstack	garrytan/gstack	역할별 슬래시 명령 묶음과 빠른 헤드리스 브라우저
andrej-karpathy-skills	multica-ai/andrej-karpathy-skills	LLM 코딩 실수를 줄이는 행동 지침을 담은 단일 CLAUDE.md
ui-ux-pro-max	nextlevelbuilder/ui-ux-pro-max-skill	검색 가능한 디자인 지식베이스와 디자인 시스템 생성 스킬

과잉 코딩을 억제하는 도구들: ponytail, andrej-karpathy-skills, mattpocock-skills

세 하네스 모두 에이전트가 필요 이상으로 코드를 불리거나 멀쩡한 코드를 통째로 다시 쓰는 습관을 교정하는 데 초점이 맞춰져 있습니다.

ponytail은 스스로를 “게으른 시니어 개발자 모드”라고 부르는 규칙 팩입니다. 동작하는 가장 단순한 해법을 고르게 하고, 새 의존성보다 표준 라이브러리를 먼저 쓰게 합니다. 특징은 앞에서 본 훅을 쓴다는 점입니다. 세션 시작 훅으로 규칙을 매번 자동으로 불러오기 때문에, CLAUDE.md에 한 번 써 두고 잊히는 문제를 줄입니다. 여기에 코드 점검, 기술 부채 기록, 리뷰용 스킬이 필요할 때 부르는 형태로 들어 있습니다. 처음 글에 적었던 “코드량 54% 감소, 토큰 20% 절감”은 원본 저장소에서 근거를 찾지 못해 뺐습니다.

andrej-karpathy-skills는 안드레이 카파시가 LLM 코딩에 대해 남긴 관찰을 바탕으로 커뮤니티가 정리한 단일 CLAUDE.md입니다. 카파시 본인이 만든 것이 아니라는 점은 구분해 둘 필요가 있습니다. 담긴 원칙은 네 가지입니다.

코딩 전에 생각하기: 바로 코드를 쓰지 말고 가정과 접근을 먼저 밝힌다.
단순성 우선: 요청받지 않은 추상화와 기능을 만들지 않는다.
외과적 수정: 목표 지점만 고치고 주변 코드를 함부로 손대지 않는다.
목표 중심 실행: 완료 기준을 정하고 그것을 검증하는 방향으로 움직인다.

파일 하나라 가볍게 시험해 보기 좋고, 기존 CLAUDE.md에 덧붙이는 방법도 README에 나와 있습니다. 다만 앞에서 본 대로 CLAUDE.md는 강제가 아니니, 정말 지켜야 할 것은 권한 규칙이나 훅으로 받쳐 줘야 합니다.

mattpocock-skills는 TypeScript 교육자로 알려진 맷 포콕(Matt Pocock)이 공개한 스킬 모음입니다. 테스트 주도 개발, 버그 진단, 도메인 모델링, PRD와 이슈 작성, 프로토타이핑 같은 실무 절차가 스킬로 들어 있고, 에이전트용 문서(AGENTS.md, CLAUDE.md, 스킬) 작성법을 다루는 스킬도 있습니다. 특정 클라우드나 모델에 묶인 내용이 적어 여러 에이전트에서 두루 쓰기 좋습니다.

컨텍스트와 작업 흐름을 관리하는 도구들: planning-with-files, gsd-core

두 하네스는 코드 스타일보다 “세션이 끊기거나 작업이 길어질 때 무엇을 기억하고 어떤 순서로 진행할 것인가”를 다룹니다.

planning-with-files는 Manus 방식의 파일 기반 계획을 코딩 에이전트에 옮긴 하네스입니다. 맥락이 압축되거나 /clear로 비워져도 남아 있도록 세 파일에 상태를 적습니다.

task_plan.md: 상위 작업 정의와 단계별 완료 여부
findings.md: 코드를 분석하면서 알게 된 사실과 진단
progress.md: 실제로 무엇을 바꿨는지에 대한 진행 기록

며칠씩 이어지는 마이그레이션이나 리팩터링에서 특히 쓸모가 있습니다. Claude Code에는 맥락 압축 직전에 실행되는 PreCompact 훅이 있어서, 이런 파일 기반 상태 관리와 궁합이 좋습니다.

gsd-core는 명세 주도 개발(spec-driven development) 시스템입니다. 에이전트, 스킬, 슬래시 명령, 훅을 한 번에 설치해서, 무엇을 만들지 먼저 정리하고 계획을 세운 뒤 구현과 검증으로 넘어가는 흐름을 잡아 줍니다. 처음 글에는 단계 이름까지 그림으로 그렸는데, 단계 구성은 버전에 따라 바뀔 수 있어 원본 저장소 문서를 직접 확인하시길 권합니다. Weft README가 대표 예시로 weft install gsd-core를 쓸 만큼 설치 구성이 큰 하네스라, --dry-run으로 무엇이 들어오는지 먼저 보는 것을 추천합니다.

특정 생태계에 맞춘 도구들: anthropic-skills, obsidian-skills, vercel-agent-skills

범용 규칙이 아니라 특정 벤더나 도구 생태계와의 연동에 특화된 하네스입니다.

anthropic-skills는 Anthropic이 공개한 공식 예제 스킬 모음입니다. Word·Excel·PowerPoint·PDF 문서 처리, MCP 서버 제작(mcp-builder), 스킬 작성법, 시각·웹 디자인, Claude API 가이드 등이 들어 있습니다. 이름 그대로 ‘예제’ 성격이 있으니, 중요한 데이터를 다루는 작업에 쓰기 전에는 결과물을 직접 검증하는 편이 안전합니다. MCP 서버를 직접 만들어 붙일 계획이라면 1인 개발자를 위한 MCP 도입 실전 가이드와 같이 보시면 연결이 됩니다.

obsidian-skills는 Obsidian CEO인 스테프 앙고(Steph Ango, kepano)가 만든 스킬입니다. Obsidian 마크다운, Bases, JSON Canvas를 작성·편집하고 Obsidian CLI를 다루며, 웹 문서를 정리하는 Defuddle 연동도 들어 있습니다. 개인 지식 볼트를 에이전트로 주기적으로 정리하고 싶은 경우에 맞습니다.

vercel-agent-skills는 Vercel이 공개한 공식 스킬입니다. Next.js·React 모범 사례, 컴포넌트 구성 패턴, 뷰 트랜지션, React Native, Vercel 배포, 웹 디자인과 글쓰기 가이드가 들어 있습니다.

종합 워크플로와 디자인 도구: gstack, ui-ux-pro-max

gstack은 와이콤비네이터(Y Combinator) 대표 가리 탄(Garry Tan)이 공개한 Claude Code 스킬 묶음과 빠른 헤드리스 브라우저입니다. README를 보면 역할별 슬래시 명령이 꽤 많습니다. 웹 페이지를 열어 보는 /browse, 스테이징 URL이나 API를 돌아다니며 동작을 확인하는 /qa, 변경을 검토하는 /review, 배포 전 확인을 맡는 /ship, 계획을 검토하는 /plan-ceo-review·/plan-eng-review 등이 서로 산출물을 넘겨받는 구조입니다. 이 하네스는 자체 ./setup 스크립트로 설치되기 때문에, Weft에서도 동의가 필요한 ‘위임형’ 하네스로 분류됩니다.

ui-ux-pro-max는 UI 구축과 UX 디테일에 초점을 맞춘 디자인 지식 스킬입니다. 검색 가능한 디자인 지식베이스와 배너, 브랜드, 슬라이드, 디자인 시스템 생성 스킬로 구성됩니다. 2026년 10월 확인한 README 기준으로 컬러 팔레트 192종, 폰트 조합 74종, UX 가이드라인 119개를 담고 있다고 소개합니다. 처음 글의 숫자와 달라서 README 기준으로 고쳤고, 업데이트가 잦은 저장소라 숫자는 바뀔 수 있습니다.

어떤 조합을 쓸지 정하기

하네스가 많다고 다 깔면 CLAUDE.md와 스킬끼리 부딪히고 맥락만 무거워집니다. 저는 아래처럼 작업 성격별로 두세 개만 고르는 쪽을 권합니다.

개인 프로젝트·빠른 프로토타입: ponytail(과잉 설계 억제) + gsd-core(명세→구현 흐름)
풀스택 웹 앱·Vercel 배포: vercel-agent-skills(React·Next.js 규칙) + ui-ux-pro-max(디자인 시스템)
며칠짜리 리팩터링·백엔드 작업: planning-with-files(장기 작업 상태 유지) + gstack(QA와 브라우저 확인)

실제로 적용할 때는 이 순서를 추천합니다.

먼저 미리보기: weft install ponytail --dry-run으로 어떤 파일이 어디에 들어오는지 확인합니다.
프로젝트 범위로 설치: weft install ponytail --cli claude-code --scope local로 전역이 아닌 이 저장소에만 넣습니다.
변경 내용 확인: git diff와 git status로 .claude/ 아래 새로 생긴 스킬, 훅, 설정을 열어 봅니다. 훅 스크립트는 특히 꼼꼼히 읽습니다.
작은 작업으로 시험: 에이전트에게 간단한 기능 추가를 맡기고, 전보다 코드가 단순해졌는지, 불필요한 의존성을 넣지 않는지 비교합니다.
맞지 않으면 바로 제거: weft uninstall ponytail로 영수증 기준 정확히 되돌립니다.

설치한 하네스가 CLAUDE.md에 넣는 규칙을 읽다 보면 TDD, YAGNI, Fail Fast 같은 약어가 계속 나옵니다. 각각이 에이전트에게 어떤 행동을 요구하는지는 AI 코딩 에이전트 필수 약어 사전에 풀어 두었습니다.

자주 묻는 질문

CLAUDE.md에 “절대 하지 마”라고 썼는데 왜 가끔 무시하나요?

공식 문서가 밝히듯 CLAUDE.md는 맥락이지 강제 설정이 아니기 때문입니다. 확실히 막아야 하는 동작은 .claude/settings.json의 deny 규칙이나 PreToolUse 훅으로 옮기세요. CLAUDE.md가 너무 길거나 규칙끼리 모순되는 경우에도 지켜지는 정도가 떨어집니다.

하네스를 여러 개 같이 설치해도 되나요?

됩니다. 다만 비슷한 역할의 하네스 두 개가 서로 다른 지시를 넣으면 에이전트가 어느 쪽을 따를지 예측하기 어려워집니다. 과잉 코딩 억제용은 하나만, 작업 흐름 관리용도 하나만 고르는 식으로 역할이 겹치지 않게 조합하는 것을 권합니다.

Weft로 설치한 하네스는 Codex나 Cursor에서도 쓰나요?

Weft는 같은 카탈로그로 Claude Code, Codex, Gemini, Cursor, opencode를 대상으로 하고, 설치할 때 --cli로 어디에 넣을지 고릅니다. 다만 하네스마다 CLI별 지원 범위가 다를 수 있으니 weft info [이름]으로 먼저 확인하세요. 에이전트별 차이는 Cursor vs Claude Code 요금 비교에도 정리해 두었습니다.

남이 만든 훅을 설치해도 안전한가요?

훅은 내 계정 권한으로 셸 명령을 실행합니다. Weft는 하네스 자체 설치 스크립트를 내 컴퓨터에서 돌리지 않는 구조이지만, 설치된 훅 스크립트가 세션 중에 실행되는 것은 별개 문제입니다. 설치 후 .claude/hooks/와 설정 파일의 hooks 항목을 반드시 읽어 보고, 이해하지 못하는 스크립트는 지우는 편이 낫습니다.

CI에서 하네스를 씌운 에이전트를 돌려도 되나요?

가능하지만 권한 설정을 먼저 정해야 합니다. 프로젝트 .claude/settings.json의 권한 규칙과 훅은 비대화형 실행에서도 그대로 적용되므로, 허용 목록 방식(--permission-mode dontAsk)과 함께 쓰는 것이 안전합니다. 에이전트별 헤드리스 실행법과 YOLO 모드의 위험은 AI 코딩 에이전트 9종 총정리에 따로 정리했습니다.

마치며

AI 시대의 코딩 생산성을 가르는 차이는 모델 버전보다, 개발자가 모델에 어떤 구조적 제약을 씌우고 어떤 실행 환경을 주느냐에 달려 있습니다. 다만 하네스는 마법이 아니라 CLAUDE.md, 권한 규칙, 훅, 스킬, 서브에이전트라는 평범한 설정 파일의 조합입니다. 이 다섯 가지를 이해하고 나면 남이 만든 하네스도 골라 쓰고, 맞지 않는 부분은 직접 고칠 수 있게 됩니다.

하네스를 씌운 에이전트가 만든 코드를 그대로 병합하기 불안하다면 다른 에이전트에게 리뷰를 한 번 더 맡기는 방법도 있습니다. Claude Code에서 Codex 리뷰를 붙이는 방법은 codex-plugin-cc 가이드에, 바이브 코딩으로 만든 서비스를 운영 단계로 올릴 때 챙길 구조는 바이브 코딩 프로덕션 아키텍처 가이드에 정리했습니다.

전체 하네스 목록과 최신 카탈로그는 Weft 공식 저장소인 github.com/goyoon2/weft에서 weft catalog 안내와 함께 확인할 수 있습니다. 참고 원문 및 영감 출처: Threads @go__yoon

DP42 주간 노트 구독하기

매주 한 번, AI 도구·솔로빌더 사례·작은 제품 수익화 노트를 선별해서 보냅니다. 사이트에 다시 올 이유를 이메일로 만들어 드립니다. 스팸은 보내지 않습니다.

무료 구독하러 가기

관련 글: AI 도구 | 창업가 스토리 | DP42 소개