Claude Code용 자율 개발 플러그인 (markshust/hcf)

Claude Code를 위한 자율 개발 플러그인입니다. PM(Product Manager)을 통해 요구사항을 정의하고, 병렬 워커들이 TDD(Test-Driven Development)를 사용하여 모든 것을 구현하도록 합니다.

• 개요 (Overview)
• 시작하기 (Getting Started)
• 작동 방식 (How It Works)
• 참고 자료 (Reference)
• 아키텍처 (Architecture)
• 고급 설정 (Advanced Configuration)
• 설계 원칙 (Design Principles)
• 개발 (Development)
• 변경 로그 (Changelog)
• 기여하기 (Contributing)
• 라이선스 (License)

HCF는 계획 수립(planning) (인간 개입 필요)과 실행(execution) (완전 자율)을 분리합니다:

Planning → 요구사항에 대한 인간 + AI 협업
Execution → 병렬 TDD 워커의 자율적 구현

마켓플레이스를 추가하고, 설치한 다음, 리로드를 수행하세요:

/plugin marketplace add markshust/hcf
/plugin install hcf@hcf
/reload-plugins

/project-setup

프로젝트를 대화형으로 구성합니다:

• 기술 스택 자동 감지 (Laravel, React 등)
• 테스트, 린팅(linting), 아키텍처에 대해 질문
• .claude/ 설정 디렉토리 생성

원하는 것을 설명하기만 하면 됩니다:

"JWT를 사용하여 사용자 인증을 구현하는 것을 도와줘"

plan-create 스킬이 자동으로 활성화되어 다음 작업을 수행합니다:

발견 및 브레인스토밍(Discover & brainstorm)— 코드베이스를 탐색하고 시니어 엔지니어가 포착할 수 있는 범위/가정 순열을 열거합니다. - 작업에 대한 feature/{plan-name} 브랜치를 생성합니다. - 반드시 답변해야 하는 항목(must-answer) 대 **침묵하면 기본값으로 설정될 항목(will-default-if-silent)**으로 분류된 근거 있는 명확화 질문을 합니다. - 종속성을 가진 작업들로 분해합니다. - 테스트 설명으로서 요구사항을 작성합니다. - 작업 파일과 함께 .claude/plans/user-auth/를 생성합니다 (또는 구성된 플랜 디렉토리). - 실행 전에 격차를 찾기 위해 사후 계획 파이프라인(post-plan pipeline) 에이전트(기본값: 악마의 변호인)를 실행합니다.

계획 수립이 완료되면, 다음 질문을 받게 됩니다:

자율 구현을 시작할 준비가 되었습니까?

• 예, 지금 시작하기 (Yes, start now)
• 아니요, 나중에 실행하겠습니다 (No, I'll run it later)

세션 지속성(Session persistence)은 Claude Code에 기본으로 내장되어 있어 플러그인이 필요하지 않습니다. 자동 압축(Auto-compaction)이 컨텍스트 제한을 처리하며, 모든 실행 상태(작업 상태, 요구 사항 체크박스, 재시도 횟수)는 계획 파일(plan files)에 저장되므로, 중단된 실행은 계획을 다시 실행함으로써 재개됩니다. 대규모 계획의 경우, 실행이 사용자의 개입 없이 완료되도록 목표(goal)를 먼저 설정할 수 있습니다:

/goal the user-auth plan run reached a terminal state: plan-orchestrate output ALL_TASKS_COMPLETE or TASKS_BLOCKED

완료된 후에는 브랜치를 푸시하고 PR(Pull Request)을 생성하라는 메시지가 표시됩니다 (사용자의 허가 없이 절대 수행되지 않습니다).

후크 지점 (Hook points):

등록된 에이전트가 실행될 수 있는 후크 지점은 정확히 8개입니다:

기본적으로 devils-advocate만 등록되어 있습니다 (post-plan에서). 권위 있는 참고 자료는 HOOKS.md를 참조하십시오 — 전체 프론트매터 스키마, 결정론적 탐색 루틴, 그리고 동점 처리/순서 지정 규칙을 확인하세요.

등록 프론트매터 (Enrollment frontmatter):

에이전트는 다음 세 가지 키를 프론트매터에 추가하여 자신을 등록합니다:

name: devils-advocate
description: "..."
...

파이프라인 사용자 정의하기 (Customizing the pipeline):

프론트매터(frontmatter)를 편집하여 에이전트를 활성화, 추가, 제거 또는 순서를 재배열할 수 있습니다. 중앙 파일은 절대 아닙니다.

내장 에이전트 활성화하기.standards-enforcer

등록 시에 주석 처리되어 제공됩니다. phase (및 선택적 order/mode)의 주석을 해제하여 사용합니다:--- name: standards-enforcer description: "..." model: opus tools: Read, Edit, Glob, Grep # 구현 후 코드 표준 강제를 활성화하려면 다음 줄의 주석을 해제하세요: phase: post-implementation order: 50 mode: batch ---

**사용자 정의 게이트 추가하기.**프로젝트의 .claude/agents/ 디렉터리에 에이전트 파일을 넣고 phase를 지정하면 자동으로 등록됩니다:--- name: doc-updater description: "구현 변경 시 문서를 업데이트합니다." model: sonnet tools: Read, Edit, Glob, Grep phase: post-implementation order: 100 mode: single --- 당신은 문서 업데이트 에이전트입니다. 당신의 임무는... {에이전트의 동작, 프로세스 및 출력 형식을 정의하세요}

에이전트 비활성화하기.phase 키를 제거하거나 주석 처리하면 됩니다. 토글할 조건은 없습니다.

에이전트의 파일명(.md 제외)은 프론트매터의 name과 일치해야 합니다. .claude/agents/ 내의 로컬 에이전트는 동일한 name을 가진 플러그인 에이전트를 덮어씁니다 (로컬 파일이 완전히 우선합니다). 이 덮어쓰기는 파일명이 아닌 프론트매터의 name을 기준으로 합니다.

실제로 등록된 것을 확인하기. 프론트매터를 편집한 후, 디스커버리 스크립트를 실행하여 적용되었는지 확인하세요. 에이전트가 작동하지 않을 때 가장 먼저 시도해야 할 것입니다:

$(claude plugin path hcf)/hooks/discover-hooks.sh

# hook: pre-plan
(비어 있음 — 이 훅에서는 등록된 에이전트 없음)
# hook: post-plan
...

하나의 훅에 대해 --hook=post-plan을 추가하거나, 기계가 읽을 수 있는 출력을 위해 --json을 사용하세요. HCF의 계획 기능은 에이전트 파일을 나열하는 대신 이 정확한 스크립트를 실행하므로, 출력되는 것이 실제로 실행될 내용입니다.

0이 아닌 종료 코드는 디스커버리가 진정으로 실패했음을 의미합니다 — 훅이 비어 있는 것과는 다릅니다. 종료 코드 3

에이전트 파일이 유효하지 않은 phase 또는 mode를 선언했음을 의미합니다 (메시지에서 파일을 명시하고 수정 방법을 알려줍니다); 종료 코드 4

이는 실행 도중에 등록(enrollment) 내용이 변경되었음을 의미합니다. 이는 HCF가 의도적으로 중단하는 것이며, 설정한 파이프라인과 다르게 조용히 실행되는 것을 방지합니다.

이전 버전의 HCF에서는 pipeline.md이라는 중앙 파일에 파이프라인을 구성했습니다:
:claude/pipeline.md

하지만 이 파일은 더 이상 읽히지 않습니다. 이제 에이전트 프런트매터(agent frontmatter)가 유일한 파이프라인 설정 출처입니다. 만약 남아있는 .claude/pipeline.md 파일이 있다면, HCF는 사용자가 plan-create와 plan-orchestrate를 실행하여 설정을 에이전트 프런트매터로 마이그레이션하고 파일을 제거할 때까지 차단합니다. 이 과정은 /project-update로 처리되며,

/project-update는 절대 차단되지 않으며, 파일이 사라지면 게이트가 자동으로 해제됩니다.

플랜을 생성한 후, HCF는 작업 의존성 그래프를 시각화하여 실행 전에 병렬 처리와 순서를 확인할 수 있게 합니다:

001 ─┬─► 002 ─┬─► 005
│ │
└─► 003 ─┘
...

이것은 오케스트레이터에게 어떤 작업들이 병렬로 실행될 수 있고, 어떤 작업들은 기다려야 하는지를 알려줍니다. 이 예시에서:

배치 1: Task 001 (의존성 없음)
배치 2: Tasks 002, 003, 004 (모두 001에만 의존)
배치 3: Tasks 005, 006 (005는 002+003에 의존; 006은 004에 의존)

각 배치 내의 독립적인 작업들은 동시에 실행됩니다:

배치 1: Task 001 (의존성 없음) → 워커 1개
배치 2: Tasks 002, 003, 004 → 병렬 워커 3개
배치 3: Tasks 005, 006 → 병렬 워커 2개

100개의 작업이 순차적으로 100번 실행되는 대신 5~10개의 배치로 완료될 수 있습니다.

각 작업은 엄격한 Red → Green → Refactor 단계를 따릅니다:

• 하나의 요구사항에 대해 실패하는 테스트 작성
• 통과하기 위한 최소 코드 작성
• 테스트가 녹색(green) 상태를 유지하는 동안 리팩토링
• 다음 요구사항에 대해 반복
• 작업 완료 시 커밋

# Task 001: User 모델 생성
**상태**: 보류 (pending)
**의존성**: 없음 (none)
...

요구사항은 테스트 이름이 됩니다.

모든 스킬은 /skill-name으로 직접 호출하거나, 사용자의 요청이 해당 설명과 일치할 때 Claude에 의해 자동으로 트리거될 수 있습니다.

어떤 스킬도 .claude/hcf.json을 생성하거나 수정하지 않습니다.

/hcf:project-setup은 이 파일에 대해 묻지 않으며, /hcf:project-update는 이미 작성된 경우에만 유효성을 검사합니다. 이 파일이 없는 것이 정상적인 상황이지, 설정이 불완전하다는 의미가 아닙니다.잘못 구성된 값은 폴백(fallback)하는 대신 실행을 중단시킵니다. 만약 plansDir이 절대 경로이거나 프로젝트 외부를 벗어나거나 빈 문자열로 설정되면, HCF가 이를 보고하고 거부합니다. 요청한 것이 docs/plans임에도 불구하고 조용히 .claude/plans에 계획 파일을 작성하는 것이 더 나쁜 결과입니다. 이 경우 훨씬 나중에 잘못된 디렉터리가 채워지고 있다는 사실을 알게 될 것입니다.

계획(Plans)의 위치를 변경한 후에는 폴더를 직접 이동해야 합니다. HCF는 이를 마이그레이션하지 않습니다. /hcf:project-update는 .claude/plans에 여전히 계획 폴더가 남아 있는 경우 경고합니다.

계획은 일시적입니다(ephemeral). 계획은 문서화가 아니라 단일 실행의 작업 상태입니다. /hcf:plan-orchestrate는 계획 파일을 커밋하지 않습니다. 구현을 스테이징하고 계획 디렉터리는 제외합니다. 작업이 커밋되면 코드와 테스트가 진실의 원천(source of truth)이 됩니다. 계획을 보관해 두면 기능이 변경되는 즉시 구식이 되며, 나중에 이를 읽는 에이전트는 오도될 것입니다. 실행이 진행 중일 때는 폴더를 유지하여 중단된 실행이 재개될 수 있도록 하고, 브랜치가 병합되면 삭제하십시오. 계획이 git에 완전히 포함되지 않도록 하려면 해당 디렉터리를 .gitignore에 추가하세요.

프로젝트가 무엇으로 해결되는지 보려면 다음을 사용하세요:

$(claude plugin path hcf)/hooks/resolve-plans-dir.sh

순수 TDD(Test Driven Development) - Gherkin/BDD를 사용하지 않으며, 요구사항이 테스트 이름에 직접 매핑됩니다.
기본적으로 병렬 처리(Parallel by default) - 독립적인 작업을 자동 감지하여 동시성을 극대화합니다.
100% 이식성(portable) - 생성된 CLAUDE.md는 모든 프로젝트에서 동일합니다.
명시적 종속성(Explicit dependencies) - 작업이 자신이 의존하는 것을 선언합니다.
우아하게 실패(Fail gracefully) - 3회 재시도한 후 차단하고 다른 작업을 계속 진행합니다.

• Claude Code CLI
• Git 저장소
• 프로젝트에 구성된 테스트 프레임워크

--plugin-dir 플래그를 사용하여 게시하지 않고 로컬에서 플러그인을 테스트하세요.

claude --plugin-dir /path/to/hcf

스킬은 플러그인 이름으로 네임스페이스됩니다:

/hcf:project-setup

/hcf:plan-create [설명]

/hcf:plan-orchestrate [플랜-이름]

disable-model-invocation: true가 설정된 스킬(예: project-setup)은 수동 호출이 필요합니다. 다른 스킬들은 설명에 기반하여 자동으로 트리거됩니다.

플러그인으로 Claude Code 시작하기:
cd ~/Sites/your-test-project claude --plugin-dir ~/Sites/hcf

플러그인이 로드되었는지 확인하기:
/help

스킬들은 hcf 아래에 나타나야 합니다.