Working Guide / v1
하네스 작업 가이드
좋은 지시문을 쓰는 법이 아니라, 설계 승인부터 완료 증거까지 일의 순서를 고정하는 실무 가이드입니다.
01 / Concept
하네스와 프롬프트
하네스는 에이전트가 반복해서 올바른 절차를 따르도록 컨텍스트, 명세, 실행 가드, 검증과 운영 증거를 하나의 작업 시스템으로 묶는 장치다.
프롬프트 엔지니어링
한 번의 요청을 더 명확하게 표현한다.
좋은 응답을 얻을 가능성을 높이지만 후속 단계의 실행과 완료 판정은 보장하지 않는다.
하네스 엔지니어링
요청 전후의 역할, 순서, 산출물, 승인과 증거를 설계한다.
사람과 에이전트가 같은 규칙으로 작업하고 완료 주장을 재현 가능하게 검토한다.
02 / Workflow
작업 순서
일은 두 갈래입니다. 없던 것을 새로 만드는 신규제작과, 이미 운영 중인 것을 고치고 더하는 SM입니다. 시작점과 위험과 끝나는 지점이 서로 다르므로 순서도 다릅니다. 아래에서 갈래를 골라 나란히 비교해 보십시오.
SM · 개선·추가 아홉 단계
백지가 아니라 그 시스템에 이미 쌓인 문서에서 출발하고, 잘못 만드는 것보다 모르고 깨뜨리는 것이 더 큰 위험이며, 배포가 아니라 그 문서를 다시 닫는 것으로 끝납니다. 괄호 안은 kiwi HR 시스템에서 그 자리에 해당하는 실물입니다.
현행 확인
통과 조건바꾸려는 화면의 문서가 있고 마지막 확인일이 아직 유효해야 다음으로 간다. 없거나 낡았으면 문서부터 만든다.
읽는 것
- 대상 화면의 모듈 문서(kiwi는 spec-docs)
- 그 문서 머리말의 마지막 확인일
- 그 확인일 이후 대상 영역을 건드린 커밋
남기는 것
- 현행 확인 판정 — 문서가 유효한가, 낡았는가
권장 문서 · AI가 채웁니다
current-state.md바꾸려는 화면의 문서와 마지막 확인일, 그 뒤의 커밋을 대조해 유효·낡음을 판정한다.
이 문서를 만들어야 합니다.
개선 정의
통과 조건고칠 것과 더할 것이 기존 문서의 어느 대목인지 주소로 지목되어야 한다. 지목되지 않으면 문서가 현행을 담고 있지 않거나 개선안이 아직 생각이 아니다.
읽는 것
- 모듈 문서의 사용자·관리자 영역(kiwi는 A1–A8)
- 모듈 문서의 운영자·개발자 영역(kiwi는 B1–B10)
남기는 것
- 고칠 절과 더할 절의 목록 — 매뉴얼 문서 주소와 절 앵커로
- 하지 않을 것
권장 문서 · 사용자가 씁니다
change-definition.md고칠 절과 더할 절을 기존 문서의 대목으로 지목하고, 하지 않을 것을 함께 적는다.
이 문서를 만들어야 합니다.
영향 분석
통과 조건영향받는 모듈·데이터·화면·권한이 목록으로 나오고, 각 항목에 확인함·영향 없음·확인 필요 중 하나가 붙어야 한다.
읽는 것
- 문서 머리말의 관련 모듈·관련 테이블
- 문서 머리말의 메뉴 코드·권한 그룹
- 데이터 문서(kiwi는 spec-db의 테이블·함수)
남기는 것
- 영향 목록 — 항목마다 확인함·영향 없음·확인 필요
권장 문서 · AI가 채웁니다
impact-analysis.md영향받는 모듈·데이터·화면·권한을 목록으로 뽑고 항목마다 확인함·영향 없음·확인 필요를 붙인다.
이 문서를 만들어야 합니다.
기술 설계
통과 조건기술 선택이 모든 인수 조건을 다룬다.
읽는 것
- 개선 정의와 영향 목록
남기는 것
- 기존 동작을 깨지 않는 방법
- 되돌리는 방법
권장 문서 · AI가 채웁니다
plan.md기술 계획과 데이터, 인터페이스, 실패 처리와 검증 전략을 기록한다. 고치는 일이라면 기존 동작을 깨지 않는 방법과 되돌리는 방법을 함께 적는다.
이 문서를 만들어야 합니다.
작업 분해
통과 조건테스트·구현·매뉴얼·배포 작업이 추적된다.
읽는 것
- 기술 설계
남기는 것
- 작업 목록 — 작업마다 되돌리는 방법
권장 문서 · AI가 채웁니다
tasks.md테스트, 구현, 매뉴얼, 배포 작업을 순서와 독립 변경 단위로 나눈다. 작업마다 되돌리는 방법을 남긴다.
이 문서를 만들어야 합니다.
격리 구현
통과 조건관련 테스트가 실패 이유를 증명한 뒤 통과하고, 화면 동작을 바꿨다면 실제 브라우저 검사도 같은 근거를 남긴다.
읽는 것
- 작업 목록
남기는 것
- 선언한 범위 안의 코드 변경
권장 문서 · AI가 채웁니다
task-report.md선언한 범위 안에서 무엇을 바꿨고 무엇으로 확인했는지 작업 단위로 기록한다.
이 문서를 만들어야 합니다.
독립 검토
통과 조건새 동작과 기존 동작 불변이 함께 통과하고, 영향 분석에서 확인 필요로 남긴 항목이 하나도 남지 않아야 한다.
읽는 것
- 영향 목록 — 여기서 채점표가 된다
남기는 것
- 새 동작과 기존 동작 불변의 실행 증거
권장 문서 · AI가 채웁니다
verification-report.md새 동작과 기존 동작 불변을 함께 검증한 명령과 결과를 남긴다.
이 문서를 만들어야 합니다.
매뉴얼 동기화
통과 조건지목된 주소마다 고침·영향 없음(사유)·미확인 중 하나가 붙고, 고친 문서의 확인일이 갱신되어야 한다. 미확인이 하나라도 남으면 닫히지 않는다.
읽는 것
- 개선 정의가 지목한 주소 목록 — 여기서 채점표가 된다
남기는 것
- 고쳐진 매뉴얼 문서
- 갱신된 확인일과 확인 범위
- 주소별 판정 — 고침·영향 없음(사유)·미확인
권장 문서 · AI가 채웁니다
manual-impact.md독자별 매뉴얼의 영향을 판정하고, 고친 대목 또는 영향 없음의 구체적 이유를 적는다.
이 문서를 만들어야 합니다.
통합 배포
통과 조건접근성·반응형 브라우저 검사와 후보·활성 경로 스모크가 모두 통과했다.
읽는 것
- 배포 절차
남기는 것
- 배포 기록과 되돌아갈 기준점
권장 문서 · AI가 채웁니다
deployment-report.md후보 검증과 활성화, 스모크 결과와 되돌아갈 기준점을 남긴다.
이 문서를 만들어야 합니다.
앞 단계가 만든 문서가 뒤 단계의 채점표가 됩니다. 영향 분석이 남긴 목록으로 검증을 채점하고, 개선 정의가 지목한 절 목록으로 문서 갱신을 채점합니다. 그래서 앞을 대충 적으면 뒤에서 채점할 것이 없어집니다. 실제로 이 순서를 밟은 기록은 문서에서 볼 수 있습니다.
신규제작 열 단계
각 단계는 목적뿐 아니라 관찰 가능한 산출물과 통과 조건을 가집니다.
요청 계약
문제, 대상, 성공 조건, 범위와 외부 효과를 합의한다.
- 산출물
- 검증 가능한 요청 계약
- 통과 조건
- 목적과 비목표가 구분되었다.
권장 문서 · 사용자가 씁니다
request.md목적과 비목표, 성공 조건, 승인이 필요한 외부 효과를 합의해 적는다.
이 문서를 만들어야 합니다.
브레인스토밍
대안을 비교하고 핵심 경험과 경계를 설계한다.
- 산출물
- 승인된 design.md
- 통과 조건
- 사용자가 설계를 명시적으로 승인했다.
기능 정의
승인된 설계를 구현 가능한 기능과 인수 조건으로 정의한다.
- 산출물
- spec.md와 매뉴얼 영향 판정
- 통과 조건
- WHAT과 완료 조건이 구현 전에 승인되었다.
기술 설계
데이터, 인터페이스, 실패 처리와 검증 전략을 정한다.
- 산출물
- plan.md
- 통과 조건
- 기술 선택이 모든 인수 조건을 다룬다.
남기는 문서 · AI가 채웁니다
기술 계획과 데이터, 인터페이스, 실패 처리와 검증 전략을 기록한다. 고치는 일이라면 기존 동작을 깨지 않는 방법과 되돌리는 방법을 함께 적는다.
작업 분해
작업을 테스트 우선의 독립 단위와 안전한 순서로 나눈다.
- 산출물
- tasks.md
- 통과 조건
- 테스트·구현·매뉴얼·배포 작업이 추적된다.
격리 구현
변경 경계를 격리하고 RED→GREEN→REFACTOR로 구현한다.
- 산출물
- 작은 코드 변경과 실행 기록
- 통과 조건
- 관련 테스트가 실패 이유를 증명한 뒤 통과하고, 화면 동작을 바꿨다면 실제 브라우저 검사도 같은 근거를 남긴다.
독립 검토
구현자와 분리된 관점으로 계약, 회귀와 공개 경계를 검토한다.
- 산출물
- 검토 의견과 수정 근거
- 통과 조건
- 중대한 발견이 해결되거나 남은 위험으로 기록되었다.
매뉴얼 제작
변경된 기능과 독자별 설명·명령·증거를 같은 상태로 맞춘다.
- 산출물
- 갱신된 매뉴얼 또는 manual-impact: none 근거
- 통과 조건
- 영향 판정과 제품-매뉴얼 정합성 검증이 끝났다.
통합 배포
제품과 매뉴얼을 한 후보로 검증하고 함께 활성화한다.
- 산출물
- 버전 릴리스와 스모크 결과
- 통과 조건
- 접근성·반응형 브라우저 검사와 후보·활성 경로 스모크가 모두 통과했다.
재평가
동일한 기준으로 효과, 회귀와 남은 위험을 다시 측정한다.
- 산출물
- 재평가 결과와 다음 개선 항목
- 통과 조건
- 근거가 판정을 지지하며 후속 작업이 명시되었다.
권장 문서 · AI가 채웁니다
reassessment.md같은 기준으로 효과를 다시 재고, 남은 위험과 다음 개선 항목을 적는다.
이 문서를 만들어야 합니다.
03 / Who and how
일을 끌고 가는 것들
순서와 게이트가 정해져도 그것을 실제로 끌고 가는 것이 있어야 합니다. 세 층입니다 — 무엇을 만들지 고정하는 명세, 어떻게 일할지 규율하는 실행 규율, 그 일을 누가 맡는지 나누는 역할. 층마다 현재 쓰는 도구를 적었지만 도구가 주제는 아닙니다. 도구가 없으면 사람이 같은 자리를 맡으면 됩니다.
WHATspec-kit은 승인된 설계를 spec.md, plan.md, tasks.md로 구체화해 무엇을 만들지(WHAT)를 정의한다.
HOWSuperpowers는 탐색, 테스트 우선 구현, 실행 분리와 완료 검증을 통해 어떻게 일할지(HOW)를 규율한다.
명세
무엇을 만들지 누가 고정하나
현재 구현은 spec-kit입니다.
도구가 없다면 — 설계·명세·계획·작업 분해를 사람이 같은 문서로 적는다. 도구는 서식을 대신 채울 뿐이고, 승인 없이 다음으로 가지 않는다는 규칙은 도구가 아니라 순서가 정한다.
speckit-constitution저장소의 원칙을 문서로 고정하고 딸린 템플릿을 함께 맞춘다.speckit-specify자연어 요청을 기능 명세로 옮긴다.speckit-clarify명세의 미정 지점을 질문으로 좁히고 답을 명세에 적어 넣는다.speckit-checklist그 기능에 맞는 점검 목록을 만든다.speckit-plan설계 산출물을 만들어 기술 계획으로 고정한다.speckit-tasks의존 순서가 있는 작업 목록을 만든다.speckit-analyze명세·계획·작업이 서로 어긋나지 않는지 대조한다. 고치지 않고 어긋남만 낸다.speckit-implement작업 목록을 순서대로 실행한다.speckit-converge현재 코드와 명세를 대조해 아직 만들지 않은 일을 작업 목록에 덧붙인다.speckit-taskstoissues작업을 의존 순서가 있는 이슈로 옮긴다.speckit-agent-context-update에이전트가 읽는 컨텍스트 파일의 spec-kit 절을 갱신한다.
실행 규율
어떻게 일할지 누가 규율하나
현재 구현은 Superpowers입니다.
도구가 없다면 — 탐색·테스트 우선·완료 검증을 수동 체크리스트로 재현한다. 핵심은 스킬 이름이 아니라 승인과 증거를 건너뛰지 않는 것이다.
HOW / 브레인스토밍
brainstorming
문제와 대안을 탐색한 뒤 design.md에 합의된 결정을 남긴다.
- 산출물
- 승인된 설계실제 문서 보기 — 5240lab 하네스 공개 사이트 설계
- 증거 게이트
- 설계 승인 전에는 기능 정의나 구현을 시작하지 않는다.
HOW / 격리 구현
test-driven-development
요구를 드러내는 RED를 먼저 관찰하고 최소 구현으로 GREEN을 만든 뒤 REFACTOR한다.
- 산출물
- 실패와 통과가 연결된 테스트 증거실제 문서 보기 — Foundational task report
- 증거 게이트
- RED → GREEN → REFACTOR 순서를 지킨다.
HOW / 작업 분해 · 격리 구현 · 독립 검토
subagent-driven-development / executing-plans
병렬성이 안전하면 작업별 하위 에이전트를 쓰고, 그렇지 않으면 계획을 순차 실행한다.
- 산출물
- 범위가 분리된 구현과 검토 기록실제 문서 보기 — .technical-label 자간 규칙 분리 보고서
- 증거 게이트
- tasks.md 순서와 파일 소유권, 독립 검토 경계를 지킨다.
HOW / 독립 검토 · 매뉴얼 동기화 · 통합 배포
verification-before-completion
제품, 매뉴얼, 배포 경로를 확인하고 실패·미실행·제약을 그대로 보고한다.
- 산출물
- 완료 주장을 뒷받침하는 최신 명령과 스모크 결과실제 문서 보기 — Phase 6~8 검증 보고서
- 증거 게이트
- 예상이나 과거 결과가 아닌 방금 실행한 증거가 있어야 완료로 판정한다.
역할 분리
그 일을 누가 맡나
현재 구현은 에이전트 정의입니다.
도구가 없다면 — 구현한 사람이 자기 코드를 검토하지 않고, 검토한 사람이 자기 지적을 닫지 않는다. 사람 셋이든 에이전트 셋이든 이 분리가 지켜지면 같은 효과가 난다.
구현한 쪽이 자기 코드를 검토하면 자기 가정을 다시 확인할 뿐이고, 검토한 쪽이 자기 지적을 닫으면 지적을 없애는 가장 쉬운 길을 고르게 된다. 셋을 나누는 이유는 능력이 달라서가 아니라 관점이 달라야 하기 때문이다.
구현자
harness-implementer
작업 하나를 구현한다. 테스트를 먼저 쓰고 실패를 눈으로 확인한 뒤 통과시킨다.
브리프의 참조 코드보다 현재 소스를 믿고, 어긋난 지점을 보고한다. 게이트가 막으면 느슨하게 하지 않고 멈춘다.
검토자
harness-reviewer
변경이 동작하는가가 아니라 옳은가를 본다. 명세 준수와 코드 품질을 따로 판정한다.
읽는 데 그치지 않고 실제 입력을 넣어 경계를 찌른다. 테스트가 무언가를 막고 있는지 구현을 망가뜨려 확인한다. 브리프와 일치함을 정확성의 증거로 삼지 않는다.
수정자
harness-fixer
검토 지적을 닫는다. 표현을 바꿔 지적을 피하는 것이 아니라 결함을 없앤다.
지적마다 재현 테스트를 먼저 써서 실패를 확인한 뒤 고친다. 고치면서 반대편을 열지 않았는지 확인한다.
한 번 돌려본 기록 · 2026-08-18
라벨 자간을 한글과 라틴으로 나누는 작업 하나를 이 세 역할로 통과시켰습니다. 구현자가 통과로 낸 것을 검토자가 뒤집었고, 검토자가 준 수정안을 수정자가 그대로 받지 않고 좁혔습니다.
- 구현자는 회귀 테스트 두 건을 붙이고 통과로 냈다.
- 검토자가 렌더된 라벨 99개를 전수 실측해, 그 테스트가 규칙이 사라지는 것은 막지만 라벨의 갈래를 잘못 붙이는 것은 잡지 못한다는 것을 찾았다.
- 수정자는 검토자의 수정안이 빈 라벨이나 기호만 있는 라벨을 자동으로 라틴 취급해 판정을 사람 대신 정해버린다고 보고, 그 경우를 명시적으로 실패시키도록 좁혔다.
다만 이 실행은 저장소에 정의된 에이전트가 그대로 등록되어 돌아간 것이 아닙니다. 프로젝트 전용 에이전트는 그 저장소를 작업 디렉터리로 열었을 때만 등록되는데, 이 작업은 상위 디렉터리에서 시작해 등록되지 않았습니다. 그래서 정의 파일의 계약을 범용 에이전트에 실어 같은 역할을 수행시켰습니다. 역할과 규율과 산출물은 정의 그대로지만, 정의한 에이전트가 그대로 돌았다는 뜻은 아닙니다.
04 / Verification
검사 실행
구현과 통합 배포의 통과 조건은 실제 브라우저 검사를 요구합니다. 그 검사가 무엇을 보는지가 없으면 통과 여부를 스스로 판정할 수 없으므로, 이 자리에 판정 기준을 적습니다. 도구 이름과 명령이 나오는 자리는 이 절 하나뿐입니다 — 다른 도구로 같은 것을 보아도 게이트는 똑같이 통과합니다.
- 도구
- Playwright · Chromium
- 명령
npm run test:browser- 뷰포트
- 375px · 768px · 1024px · 1440px
- 접근성
- axe WCAG 2.1 A/AA — 헤딩 순서는 별도 규칙으로 따로 본다
무엇을 보는가
- 네 폭에서 가로 넘침 없이 핵심 내용이 남는가
- 헤딩이 단계를 건너뛰지 않고 순서대로 내려가는가
- 모션 축소를 켠 사용자에게 애니메이션이 멈추는가
- 선언한 서체가 실제로 적재되어 방문자 OS 서체로 떨어지지 않는가
- 공개 경로가 모두 살아 있고 각 화면의 핵심 문구가 그대로인가
명령 하나로 전부 돈다. 완료 판정 전에 따로 돌리고 결과 건수를 검증 보고서에 남긴다 — 나머지 검증 명령에는 브라우저 검사가 들어 있지 않다.
주의 검사기가 자체 서버를 띄우므로 앞에서 개발 서버를 따로 띄우지 않는다. 먼저 띄우면 검사가 그 자리에서 멈춘다.
매뉴얼 동기화 채점
SM의 매뉴얼 동기화 게이트도 사람의 판단이 아니라 대조로 닫습니다. 개선 정의가 주소로 지목한 대목을 하나씩 열어 확인일을 읽고 이번 변경일과 비교합니다.
- 명령
npm run check:manual-sync- 넣는 것
- 변경일과 지목 주소 목록을 담은 변경 기록 파일. 고치지 않고 닫으려면 그 사유를 항목에 함께 적습니다.
- 판정
- 고침 — 확인일이 변경일 이후다
- 영향 없음 — 고치지 않았으나 구체적인 사유가 있다
- 미확인 — 나머지 전부
닫히지 않을 때 미확인이 하나라도 남으면 실패로 끝납니다. 사유가 비어 있는 영향 없음도 미확인으로 떨어집니다.
05 / Definition of done
매뉴얼 제작·동기화 게이트
코드가 동작하는 것만으로 완료가 아니다
사용자·개발자·근거 관리자·운영자 매뉴얼의 영향을 판정하고 제품과 함께 검증해야 합니다.
맞출 상대
- 신규제작 — 매뉴얼 제작
- 신규제작은 독자별 매뉴얼을 새로 만듭니다. 이 단계가 끝나야 고칠 대상이 생깁니다.
- SM · 개선·추가 — 매뉴얼 동기화
- SM은 이미 있는 매뉴얼에서 개선 정의가 지목한 대목을 고치고 확인일을 갱신합니다.
여기 걸린 주소는 5240lab의 매뉴얼입니다. 다른 조직이라면 자기 매뉴얼이 그 자리에 옵니다 — 중요한 것은 특정 사이트가 아니라 맞출 상대가 정해져 있다는 것입니다.
선언으로 끝나지 않게 하는 것
- 지목은 주소로 적는다개선 정의가 고칠 대목을 말로 적으면 사람만 대조할 수 있습니다. 매뉴얼의 문서 주소와 절 앵커로 적으면 그 자리를 열어 확인할 수 있습니다.
- 고친 문서의 확인일을 갱신한다매뉴얼 문서는 마지막 확인일을 머리말에 답니다. 현행 확인 단계가 그 날짜를 읽어 낡음을 판정하므로, 고치고 날짜를 갱신하지 않으면 다음 개선이 같은 자리에서 다시 걸립니다.
- 미확인을 남긴 채 닫지 않는다지목 목록의 항목마다 고침·영향 없음(사유)·미확인 중 하나가 붙습니다. 미확인이 하나라도 남으면 이 단계는 닫히지 않습니다 — 닫을 수단이 없으면 그것 자체가 다음 개선 항목입니다.
- 변경이 각 독자의 기능 설명, 명령, 증거 또는 운영 절차에 미치는 영향을 판정한다.
- 영향받는 매뉴얼을 제품과 함께 수정하고 링크·명령·표현을 실제 동작과 대조한다.
- 영향이 없으면 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 후 회귀 검사:
- 브라우저 검사 명령 / 결과(접근성·반응형):
- 독립 검토 결과:
매뉴얼 게이트:
- 영향받은 사용자 / 개발자 / 근거 / 운영 매뉴얼:
- 고친 매뉴얼 주소 / 갱신된 확인일:
- 지목 목록의 미확인 잔여 (0이어야 함):
- 정합성 검증:
- manual-impact: none (해당할 때만, 이유 필수):
릴리스:
- 제품 + 매뉴얼 통합 릴리스 ID:
- 후보 / 활성 스모크 결과:
- 남은 위험과 재평가일: