harness-loop-fullstack

아이디어 한 줄에서 시작해 문서 → 태스크 → 검증 하네스 → 자율 개발 루프까지 잇는 한글 에이전트 스킬 플러그인

A Korean agent-skill plugin for Claude Code & Codex — idea → PRD → architecture → task plan → verification harness → autonomous development loop. (English)

imageversion imagelicense imageClaude Code imageCodex

무엇을 해 주나

"이런 앱 만들고 싶어"라고 말하면, 에이전트가 요구사항·기술·설계 문서를 쓰고, 검증 가능한 태스크로 쪼개고, 태스크마다 통과 기준(게이트)을 세운 뒤, 그 기준을 통과할 때까지 스스로 구현·검증·수정을 반복합니다. 사람은 단계마다 결과를 검토하고, 루프가 돌기 시작하면 루프가 질문을 올릴 때만 답합니다.

flowchart TD
    A["PRD → TRD → Architecture → Master Plan"]
    
    A --> B["Phase"]
    B --> C["Task"]
    C --> D["Implement"]
    D --> E{"Verify"}

    E -->|FAIL| F["Fix"]
    F --> E

    E -->|PASS| G{"More Tasks?"}

    G -->|YES| C
    G -->|NO| H["Phase Complete"]

    H --> I{"Next Phase?"}

    I -->|YES| B
    I -->|NO| J["Project Complete"]

    classDef process fill:#e8f4ff,stroke:#1976d2,stroke-width:1.5px,color:#0d47a1;
    classDef decision fill:#fff8e1,stroke:#f9a825,stroke-width:1.5px,color:#5d4037;
    classDef complete fill:#e8f5e9,stroke:#43a047,stroke-width:1.5px,color:#1b5e20;

    class A,B,C,D,F process;
    class E,G,I decision;
    class H,J complete;

무엇이 다른가

• 대화가 아니라 파일이 입력입니다. 각 단계는 앞 단계의 문서만 읽습니다. 세션이 끊겨도 문서만 있으면 이어집니다.
• 구현한 세션이 스스로 합격 판정을 내리지 않습니다. 마지막 검증(task_validation)은 구현 과정을 모르는 다른 세션이 실행 중인 앱을 직접 조작해 판정합니다.
• 실패하면 고치기 전에 원인부터 분류합니다. 코드 결함·낡은 테스트·환경 문제·흔들리는 테스트를 구별하고, 코드 수정은 3회까지입니다. 소진하면 기준을 낮추지 않고 멈춰 사람에게 묻습니다.
• 병렬로 돌고, 사람을 부르는 지점이 정해져 있습니다. 태스크 의존 그래프(DAG)로 동시에 할 수 있는 태스크를 워크트리별로 나눠 돌리고, 멈추는 조건은 "답이 필요한 질문"과 "전부 완료" 둘뿐입니다.
• 완료 뒤에도 이어집니다. 기능 추가·버그 수정·리팩토링, 그리고 문서 없이 만든 코드를 이 흐름에 올리는 스킬이 있습니다.

설치

/plugin marketplace add GangJaeYu/harness_loop_full_korean
/plugin install harness-loop-fullstack@harness-loop-fullstack

버전을 고정하려면 GangJaeYu/harness_loop_full_korean@v1.15.5 처럼 붙입니다.

코덱스:

codex plugin marketplace add GangJaeYu/harness_loop_full_korean
codex plugin add harness-loop-fullstack@harness-loop-fullstack

플러그인 없이 쓰는 방법은 시작하기를 보세요.

필요한 것: git 저장소, Claude Code(또는 Codex) CLI. 루프 단계에서는 프로젝트 스택에 따라 Docker(DB 등 의존 서비스), Node·Playwright(e2e) 가 필요하고, Windows 에서는 PowerShell 7(pwsh)을 권장합니다. 병렬 운용에 Orca(ADE)를 쓸 수 있지만 없어도 됩니다.

빠르게 시작하기

빈 폴더에서 git init 하고 에이전트를 연 뒤, 순서대로 말하면 됩니다. 각 단계가 끝나면 스킬이 보고하고 멈추므로 검토하고 다음으로 넘어갑니다.

1. "이런 앱 아이디어가 있는데 정리해줘" → docs/IDEA.md
2. "PRD 써줘" → "TRD 써줘" → "아키텍처 설계해줘" → 요구사항·기술·설계 문서
3. "개발 계획 세워줘" → plan_setup/ (phase·task·STATE·LOG)
4. "하네스 세팅해줘" → 게이트 정의서와 로컬 개발 환경 스크립트
5. "개발 루프 세팅해줘" → loop_setup/LOOP.md · 실행 순서 그림 DAG.md · 구동 스크립트
6. "첫 사이클 시작하자" → 이후로는 루프가 돌고, 질문이 오면 plan_setup/STATE.md 에 답을 적습니다

이미 PRD 가 있으면 그다음 단계부터 시작하면 됩니다. 결과물이 어떻게 생겼는지는 예시 프로젝트 에서 볼 수 있습니다.

스킬 한눈에

스킬별 자세한 설명과 예시는 스킬 안내에 있습니다.

루프가 도는 동안

• 시작: 루프 세팅이 끝나면 LOOP.md 에 적힌 구동 명령으로 구동 스크립트를 띄웁니다. 스크립트가 태스크마다 새 세션을 열고, phase 가 바뀌어도 알아서 이어 갑니다.
• 질문에 답하기: Orca 모드에서는 질문이 생기면 답하기 탭이 떠서 그 자리에서 답하고 멈춘 루프를 다시 띄웁니다. 그 밖에는 plan_setup/STATE.md(병렬이면 코디네이터 워크트리의 것)의 Next Action 에 있는 질문: 아래에 답: 줄을 적고 구동 명령을 다시 실행합니다.
• 지켜보기: Orca 모드에서는 상태판(loop-status)으로 봅니다 — 구동 스크립트가 살아 있는지, 지금 판단 중인지, 슬롯마다 어느 태스크가 어디까지 왔는지, 사람에게 걸린 질문이 한 화면에 10초마다 다시 그려집니다. 구동 명령을 친 터미널에 바로 뜨고, 읽기만 하므로 아무 터미널에서나 띄우고 닫아도 됩니다(Orca 사이드바에는 구동 스크립트와 판단 세션이 나오지 않습니다). 기록은 STATE.md·LOG.md, 검증까지 끝난 결과만 기본 브랜치(main)에 들어옵니다.
• 알림: Orca 모드에서는 루프가 진행할 수 있는데 멈추면(잠든 워커, 죽은 스크립트, 사람의 답을 기다리는 워커, 새 질문) OS 알림으로 알려 주고, 태스크·phase 가 완료될 때도 한 번씩 알려 줍니다. 완료 소식이 한동안 없으면 상태판을 보세요.

운용과 문제 해결은 운용 가이드에 있습니다.

비용과 한계 (솔직하게)

• 토큰과 시간이 많이 듭니다. 태스크마다 구현·검증 세션이 따로 열리고 게이트를 여러 번 돌리는 구조라서입니다. 실사용 프로젝트(웹 ERP, 태스크 76개, 코드 약 6만 줄)는 9일 동안 입력 토큰 약 17.7억(대부분 캐시 읽기)을 썼습니다. 그 기록을 분석해 1.10.0 에서 가장 큰 낭비(상주 코디네이터, 전체의 약 30%)를 걷어냈지만, 개선 후 실제 프로젝트로 다시 재지는 않았습니다.
• 실사용 검증은 아직 한 프로젝트뿐입니다. 다른 스택·환경에서의 사례를 기다리고 있습니다.
• 코덱스는 설치와 스킬 인식까지 확인했지만(Codex CLI 0.156.1), 코덱스로 루프 전체를 돌려 보지는 않았습니다. 실사용 프로젝트는 클로드 코드로 진행했습니다.
• 구동 스크립트는 프로젝트마다 에이전트가 새로 작성합니다. 첫 구동 전에 루프 세팅이 안내하는 시험 실행(스모크 테스트)을 꼭 돌리세요.
• 작은 스크립트 한 개짜리 작업에는 과합니다. 여러 화면·여러 phase 가 있는 웹 애플리케이션을 전제로 만들었습니다.

문서

라이선스

MIT