Working Guide / v1

하네스 작업 가이드

좋은 지시문을 쓰는 법이 아니라, 설계 승인부터 완료 증거까지 일의 순서를 고정하는 실무 가이드입니다.

01 / Concept

하네스와 프롬프트

하네스는 에이전트가 반복해서 올바른 절차를 따르도록 컨텍스트, 명세, 실행 가드, 검증과 운영 증거를 하나의 작업 시스템으로 묶는 장치다.

프롬프트 엔지니어링

한 번의 요청을 더 명확하게 표현한다.

좋은 응답을 얻을 가능성을 높이지만 후속 단계의 실행과 완료 판정은 보장하지 않는다.

하네스 엔지니어링

요청 전후의 역할, 순서, 산출물, 승인과 증거를 설계한다.

사람과 에이전트가 같은 규칙으로 작업하고 완료 주장을 재현 가능하게 검토한다.

02 / Documents

문서 타임라인

기능 정의는 설계 승인 뒤, 구현 전에 작성합니다. 네 문서는 결정을 덮어쓰지 않고 다음 단계가 검토할 입력을 만듭니다.

01 · 브레인스토밍
design.md
사용자 문제, 선택한 접근, 경계와 주요 경험을 기록하는 승인된 설계 문서다.
작성 시점
탐색을 마치고 설계 승인을 받을 때 확정한다.
승인 게이트
사용자가 설계를 명시적으로 승인해야 기능 정의로 이동한다.
02 · 기능 정의
spec.md
기능이 제공할 WHAT, 인수 조건, 범위와 매뉴얼 영향을 정의한다.
작성 시점
설계 승인 뒤, 구현 전에 작성한다.
승인 게이트
모호한 요구와 매뉴얼 영향을 해소하고 승인한다.
03 · 기술 설계
plan.md
기술 계획과 데이터, 인터페이스, 실패 처리와 검증 전략을 기록한다.
작성 시점
기능 정의가 승인된 뒤 구현 방식을 선택할 때 작성한다.
승인 게이트
요구사항을 빠짐없이 구현·검증할 수 있는지 검토한다.
04 · 작업 분해
tasks.md
테스트, 구현, 매뉴얼, 배포 작업을 순서와 독립 변경 단위로 나눈다.
작성 시점
기술 계획 승인 뒤 첫 테스트를 쓰기 전에 작성한다.
승인 게이트
각 작업에 결과물과 검증 방법이 있어야 실행한다.

03 / Playbook

10단계 플레이북

각 단계는 목적뿐 아니라 관찰 가능한 산출물과 통과 조건을 가집니다.

요청 계약
문제, 대상, 성공 조건, 범위와 외부 효과를 합의한다.
산출물
검증 가능한 요청 계약
통과 조건
목적과 비목표가 구분되었다.
브레인스토밍
대안을 비교하고 핵심 경험과 경계를 설계한다.
산출물
승인된 design.md
통과 조건
사용자가 설계를 명시적으로 승인했다.
기능 정의
승인된 설계를 구현 가능한 기능과 인수 조건으로 정의한다.
산출물
spec.md와 매뉴얼 영향 판정
통과 조건
WHAT과 완료 조건이 구현 전에 승인되었다.
기술 설계
데이터, 인터페이스, 실패 처리와 검증 전략을 정한다.
산출물
plan.md
통과 조건
기술 선택이 모든 인수 조건을 다룬다.
작업 분해
작업을 테스트 우선의 독립 단위와 안전한 순서로 나눈다.
산출물
tasks.md
통과 조건
테스트·구현·매뉴얼·배포 작업이 추적된다.
격리 구현
변경 경계를 격리하고 RED→GREEN→REFACTOR로 구현한다.
산출물
작은 코드 변경과 실행 기록
통과 조건
관련 테스트가 실패 이유를 증명한 뒤 통과한다.
독립 검토
구현자와 분리된 관점으로 계약, 회귀와 공개 경계를 검토한다.
산출물
검토 의견과 수정 근거
통과 조건
중대한 발견이 해결되거나 남은 위험으로 기록되었다.
매뉴얼 동기화
변경된 기능과 독자별 설명·명령·증거를 같은 상태로 맞춘다.
산출물
갱신된 매뉴얼 또는 manual-impact: none 근거
통과 조건
영향 판정과 제품-매뉴얼 정합성 검증이 끝났다.
통합 배포
제품과 매뉴얼을 한 후보로 검증하고 함께 활성화한다.
산출물
버전 릴리스와 스모크 결과
통과 조건
후보·활성 경로 스모크가 모두 통과했다.
재평가
동일한 기준으로 효과, 회귀와 남은 위험을 다시 측정한다.
산출물
재평가 결과와 다음 개선 항목
통과 조건
근거가 판정을 지지하며 후속 작업이 명시되었다.

04 / Execution discipline

Superpowers 활용

WHATspec-kit은 승인된 설계를 spec.md, plan.md, tasks.md로 구체화해 무엇을 만들지(WHAT)를 정의한다.

HOWSuperpowers는 탐색, 테스트 우선 구현, 실행 분리와 완료 검증을 통해 어떻게 일할지(HOW)를 규율한다.

도구를 설치하지 않아도 같은 순서와 게이트를 수동 체크리스트로 재현할 수 있습니다. 핵심은 스킬 이름이 아니라 승인과 증거를 건너뛰지 않는 것입니다.

HOW / 브레인스토밍

`brainstorming`

문제와 대안을 탐색한 뒤 design.md에 합의된 결정을 남긴다.

산출물: 승인된 설계
증거 게이트: 설계 승인 전에는 기능 정의나 구현을 시작하지 않는다.

HOW / 격리 구현

`test-driven-development`

요구를 드러내는 RED를 먼저 관찰하고 최소 구현으로 GREEN을 만든 뒤 REFACTOR한다.

산출물: 실패와 통과가 연결된 테스트 증거
증거 게이트: RED → GREEN → REFACTOR 순서를 지킨다.

HOW / 작업 분해 · 격리 구현 · 독립 검토

`subagent-driven-development / executing-plans`

병렬성이 안전하면 작업별 하위 에이전트를 쓰고, 그렇지 않으면 계획을 순차 실행한다.

산출물: 범위가 분리된 구현과 검토 기록
증거 게이트: tasks.md 순서와 파일 소유권, 독립 검토 경계를 지킨다.

HOW / 독립 검토 · 매뉴얼 동기화 · 통합 배포

`verification-before-completion`

제품, 매뉴얼, 배포 경로를 확인하고 실패·미실행·제약을 그대로 보고한다.

산출물: 완료 주장을 뒷받침하는 최신 명령과 스모크 결과
증거 게이트: 예상이나 과거 결과가 아닌 방금 실행한 증거가 있어야 완료로 판정한다.

05 / Definition of done

매뉴얼 동기화 게이트

코드가 동작하는 것만으로 완료가 아니다

공개·개발자·근거 관리자·운영자 매뉴얼의 영향을 판정하고 제품과 함께 검증해야 합니다.

변경이 각 독자의 기능 설명, 명령, 증거 또는 운영 절차에 미치는 영향을 판정한다.
영향받는 매뉴얼을 제품과 함께 수정하고 링크·명령·표현을 실제 동작과 대조한다.
영향이 없으면 manual-impact: none과 구체적인 이유를 작업 보고서에 기록한다.
제품과 매뉴얼을 하나의 후보 릴리스로 검증한다.

manual-impact: none — 영향받는 독자·절차·공개 계약이 없는 구체적 이유를 함께 적는다.

릴리스 게이트: 제품 + 매뉴얼 통합 릴리스가 후보 및 활성 경로 스모크를 통과해야 완료다.

06 / Plain text

작업 템플릿

버튼이나 클립보드 API 없이 아래 일반 텍스트를 선택해 복사할 수 있습니다.

작업 시작

요청 계약:
- 사용자와 문제:
- 성공 조건:
- 범위 / 비범위:
- 외부 효과와 승인:

설계·명세:
- design.md 승인자 / 시점:
- spec.md 인수 조건:
- plan.md 실패·검증 전략:
- tasks.md 첫 RED 작업:

manual-impact: affected | none
- 영향 독자·경로 또는 none의 이유:

완료 판정

완료 증거 (RED → GREEN → REFACTOR):
- RED 명령 / 예상 실패:
- GREEN 명령 / 통과 결과:
- REFACTOR 후 회귀 검사:
- 독립 검토 결과:

매뉴얼 게이트:
- 영향받은 공개 / 개발자 / 근거 / 운영 매뉴얼:
- 정합성 검증:
- manual-impact: none (해당할 때만, 이유 필수):

릴리스:
- 제품 + 매뉴얼 통합 릴리스 ID:
- 후보 / 활성 스모크 결과:
- 남은 위험과 재평가일:

하네스 작업 가이드

하네스와 프롬프트

프롬프트 엔지니어링

하네스 엔지니어링

문서 타임라인

`design.md`

`spec.md`

`plan.md`

`tasks.md`

10단계 플레이북

요청 계약

브레인스토밍

기능 정의

기술 설계

작업 분해

격리 구현

독립 검토

매뉴얼 동기화

통합 배포

재평가