harness은(는) 무엇을 하나요?

Harness Engineering 최소 실천법. 세 가지 제약(Inspector, Worker, Reviewer)을 통해 AI의 창의성을 올바른 궤도에 가두고, TODO.md 공유 보드로 지속적 개선을 추진합니다. Harness Engineering 방법론에서 영감을 받았습니다. 즉, 가볍지만 확정적인 프로세스 프레임워크를 통해 AI 에이전트가 '자유분방함'에서 '예측 가능하게 고품질 결과물을 제공하는 것'으로 전환됩니다.

트리거 조건

즉시 실행

사용자 입력 /harness — 전체 사이클(Inspector + Worker + Reviewer 루프)
사용자 입력 /harness inspect — Inspector만 실행
사용자 입력 /harness work — Worker + Reviewer 한 번 실행
사용자 입력 /harness loop — 할 작업이 없을 때까지 Worker + Reviewer 계속 실행

사용자는 명령어 뒤에 자연어 명령을 추가하여 이번 사이클의 추가 컨텍스트를 제공할 수 있습니다. 예:

/harness 이번에는 침묵 데이터 손실 문제에 집중
/harness work 먼저 P0 환경 변수 감지부터 수정
/harness inspect 현재 골격 목표만 보정하고 Worker는 실행하지 않음

정기 스케줄링 (cron)

Claude Code 내장 CronCreate/CronDelete/CronList 도구를 사용하며, 세션 간 cron이 서로 영향을 주지 않습니다.

명령어	설명
`/harness cron "/30 * * *"`	30분마다 전체 사이클 실행
`/harness cron "/30 * * *" inspect`	30분마다 Inspector만 실행
`/harness cron "0 /2 * *" work`	2시간마다 Worker + Reviewer 실행
`/harness cron "/15 * * *" loop`	15분마다 작업 지속 처리
`/harness cron list`	현재 세션의 모든 harness cron 작업 조회
`/harness cron stop <job_id>`	지정 cron 작업 삭제
`/harness cron stop`	현재 세션의 모든 harness cron 작업 삭제 (대화형 확인 후 개별 삭제)

제한 사항:

Cron 작업은 현재 Claude Code 세션이 활성 상태인 동안에만 유효하며, 터미널을 닫으면 사라집니다.
반복 작업은 7일 후 자동으로 만료됩니다.
REPL이 유휴 상태일 때만 트리거되며, 진행 중인 대화를 방해하지 않습니다.

세 역할 프로토콜

핵심 원칙: 산출물 검증

각 역할은 자신의 산출물을 반드시 검증해야 합니다. 단순히 '완료했다'고 넘어가면 안 됩니다.

Inspector: 작업을 생성한 후 작업 설명이 충분히 명확한지, 힌트가 실행 가능한지 확인합니다.
Worker: 코드를 수정한 후 프로젝트 문서(AGENTS.md / CLAUDE.md / TODO.md / README 등)에 정의된 검증 명령을 실행하여 관련 검사를 수행합니다. 프로젝트에 종단간(E2E) 또는 실제 프로세스 검증이 정의된 경우 반드시 실행하고 결과를 기록합니다.
Reviewer: 리뷰 시 Worker가 이번 변경과 관련된 검증 명령을 실행했는지 확인합니다. 프로젝트에 E2E/실제 프로세스 검증이 정의되어 있고 변경 사항이 해당 경로에 영향을 미치는 경우, Worker가 검증하지 않았다면 거부하거나 추가 검증을 요구합니다.

종단간 검증은 선택 사항이 아닙니다. 프로젝트에 특정 E2E/실제 프로세스 검증이 없거나 외부 종속성으로 인해 실행할 수 없는 경우 그 이유를 반드시 명시적으로 기록해야 합니다.

Inspector (기획자)          — 방향 결정, 작업 발견
  ↓ TODO.md에 기록
TODO.md (공유 보드)
  ↓
Worker (수정자)            — 작업 가져오기, 코드 수정
  [대기 중] → [진행 중] → [검토 대기]
  ↓
Reviewer (검토자)          — 코드 검토, 프로젝트 규칙에 따라 승인 또는 반려 결정
  통과 → Done Log + (허용 시에만) git commit
  불통과 → [반려됨] + 수정 지침
  ↓
Worker가 [반려됨] 작업을 다시 가져옴...

작업 상태 머신

표시	의미	수정 가능한 역할
`[대기 중]`	미할당	Inspector가 추가/수정, Worker가 가져오기
`[진행 중]`	Worker가 처리 중	Worker가 가져올 때 설정, 다른 역할은 변경하지 않음
`[검토 대기]`	Worker 완료	Worker가 완료 시 설정, Reviewer가 검토
`[반려됨]`	Reviewer가 반려	Reviewer가 반려 시 설정, Worker가 다시 가져오기 가능

실행 단계

1단계 — 사용자 명령어 파싱

사용자 입력에서 추출:

cron 모드 여부: 입력에 cron 키워드 포함
모드: cron / inspect / work / loop / full (기본값)
추가 컨텍스트: 명령어 뒤의 자연어 텍스트 (있는 경우)

cron 모드이면 5단계로 이동합니다. 그렇지 않으면 2단계로 계속 진행합니다.

추가 컨텍스트를 임시 파일에 저장:

echo "사용자 추가 명령: <사용자가 입력한 자연어>" > /tmp/harness-context.txt
# 수명 주기: full 모드 다음 사이클 = inspector + worker-reviewer 모두 읽음;
# worker-reviewer가 이번 사이클에서 claude에 실제 전달 후 마무리할 때 삭제 (할 작업이 없어 조기 종료 시 유지)

추가 컨텍스트가 없으면 빈 파일을 생성합니다 (하위 프로세스가 빈 파일을 감지하면 주입하지 않음).

2단계 — 프로젝트 환경 확인

# 프로젝트 루트 디렉터리 확인
test -f TODO.md || echo "NOT_HARNESS_PROJECT"
# skill 스크립트 존재 확인 (skill 디렉터리 기준 상대 경로)
test -f ../harness/inspector.sh && test -f ../harness/worker-reviewer.sh || echo "SCRIPTS_MISSING"

환경이 올바르지 않으면 중단하고 사용자에게 알립니다.

실행 예시:

cd <project> && bash ~/.codex/skills/harness/inspector.sh
cd <project> && bash ~/.codex/skills/harness/worker-reviewer.sh --loop
HARNESS_PROJECT_DIR=/abs/path/to/project bash ~/.codex/skills/harness/inspector.sh

TODO.md가 없으면 최소 템플릿을 생성합니다:

# 프로젝트 개선 보드

## 현재 단계: 초기화

## 목표
- [ ] Inspector 첫 순회 후 작성 예정

## 완료 로그

3단계 — 모드에 따라 실행

모드: inspect

cd <프로젝트 디렉터리> && bash <skill 디렉터리>/inspector.sh

모드: work

cd <프로젝트 디렉터리> && bash <skill 디렉터리>/worker-reviewer.sh

모드: loop

cd <프로젝트 디렉터리> && bash <skill 디렉터리>/worker-reviewer.sh --loop

모드: full (기본값)

# Phase 1: Inspector 순회
cd <프로젝트 디렉터리> && bash <skill 디렉터리>/inspector.sh

# Phase 2: Worker+Reviewer 루프
cd <프로젝트 디렉터리> && bash <skill 디렉터리>/worker-reviewer.sh --loop

4단계 — 결과 출력

완료 후 사용자에게 보고:

Harness 사이클 완료

Inspector:
  - 현재 목표: ...
  - 아키텍처 판단: ...
  - 신규/조정 작업: N개

Worker+Reviewer:
  - 완료된 작업: N개
  - 반려된 작업: N개
  - 남은 대기 작업: N개

다음 사이클: /harness 입력하여 계속

5단계 — cron 모드 (내장 CronCreate/CronDelete/CronList 사용)

5.1 정기 작업 생성: `/harness cron "<cron 표현식>" [mode]`

cron 표현식과 선택적 mode(inspect / work / loop / full) 파싱
mode에 따라 prompt 내용 구성:
- full: "harness full cycle 실행. 다음을 순서대로 실행: 1. cd <프로젝트 경로> && bash <skill 경로>/inspector.sh 2. bash <skill 경로>/worker-reviewer.sh --loop 완료 후 결과 보고."
- inspect: "harness inspect 실행. cd <프로젝트 경로> && bash <skill 경로>/inspector.sh 실행. 완료 후 결과 보고."
- work: "harness work 실행. cd <프로젝트 경로> && bash <skill 경로>/worker-reviewer.sh 실행. 완료 후 결과 보고."
- loop: "harness loop 실행. cd <프로젝트 경로> && bash <skill 경로>/worker-reviewer.sh --loop 실행. 완료 후 결과 보고."
CronCreate 호출, 매개변수:
- cron: 사용자가 제공한 cron 표현식
- prompt: 위에서 구성한 prompt
- recurring: true
사용자에게 생성 성공 확인, job_id 반환

5.2 정기 작업 조회: `/harness cron list`

CronList 호출하여 현재 세션의 모든 cron job 가져오기
prompt에 "harness" 키워드가 포함된 job만 필터링
테이블 형식으로 표시: job_id | cron 표현식 | mode | 생성 시간 (있는 경우)
harness cron이 없으면 "현재 세션에 harness 정기 작업이 없습니다" 메시지 표시

5.3 정기 작업 삭제: `/harness cron stop [job_id]`

job_id 있음: CronDelete 호출하여 지정 job 삭제, 삭제 성공 확인
job_id 없음:
1. CronList 호출, harness 관련 job 필터링
2. 사용자에게 삭제할 모든 job 표시
3. 사용자 확인 후 개별적으로 CronDelete 호출하여 삭제
4. 삭제 결과 보고

하위 프로세스 입력 메커니즘

각 하위 프로세스(Inspector / Worker / Reviewer)는 claude -p로 시작되며, 입력은 세 부분으로 구성됩니다:

역할 프롬프트 — <skill 디렉터리>/prompts/inspector.md 등
프로젝트 문서 — 스크립트가 AGENTS.md, CLAUDE.md, README, TODO.md 등의 파일 내용을 자동으로 연결
사용자 추가 컨텍스트 — /tmp/harness-context.txt에서 읽어와 prompt 끝에 주입

세 부분을 연결하여 claude -p로 전달하여 하위 프로세스가 프로젝트 전체 개요와 사용자의 이번 사이클 구체적인 의도를 모두 파악할 수 있도록 합니다.

기본적으로 스크립트는 스크립트 호출 시의 현재 작업 디렉터리(pwd -P)를 프로젝트 디렉터리로 간주합니다. 다른 위치에서 호출해야 하는 경우 HARNESS_PROJECT_DIR=/abs/path/to/project로 명시적으로 재정의할 수 있습니다. skill 설치 디렉터리는 스크립트와 프롬프트 위치를 찾는 용도로만 사용되며 프로젝트 디렉터리로 간주되지 않습니다.

파일 목록

파일	역할
`prompts/inspector.md`	Inspector 역할 프롬프트
`prompts/worker.md`	Worker 역할 프롬프트
`prompts/reviewer.md`	Reviewer 역할 프롬프트
`inspector.sh`	Inspector 실행 스크립트
`worker-reviewer.sh`	Worker+Reviewer 실행 스크립트
`TODO.md`	공유 작업 보드 (프로젝트 루트 디렉터리)

/harness

harness란 무엇인가요?

즐겨 사용하는 AI에게 물어보기

문서

harness은(는) 무엇을 하나요?

트리거 조건

즉시 실행

정기 스케줄링 (cron)

세 역할 프로토콜

핵심 원칙: 산출물 검증

작업 상태 머신

실행 단계

1단계 — 사용자 명령어 파싱

2단계 — 프로젝트 환경 확인

3단계 — 모드에 따라 실행

모드: inspect

모드: work

모드: loop

모드: full (기본값)

4단계 — 결과 출력

5단계 — cron 모드 (내장 CronCreate/CronDelete/CronList 사용)

5.1 정기 작업 생성: `/harness cron "<cron 표현식>" [mode]`

5.2 정기 작업 조회: `/harness cron list`

5.3 정기 작업 삭제: `/harness cron stop [job_id]`

하위 프로세스 입력 메커니즘

파일 목록

관련 스킬

steipete/sag

steipete/oracle

steipete/peekaboo

mattpocock/design-an-interface

mattpocock/prototype

mattpocock/grill-me

즐겨 사용하는 AI에게 물어보기

문서

harness은(는) 무엇을 하나요?

트리거 조건

즉시 실행

정기 스케줄링 (cron)

세 역할 프로토콜

핵심 원칙: 산출물 검증

작업 상태 머신

실행 단계

1단계 — 사용자 명령어 파싱

2단계 — 프로젝트 환경 확인

3단계 — 모드에 따라 실행

모드: inspect

모드: work

모드: loop

모드: full (기본값)

4단계 — 결과 출력

5단계 — cron 모드 (내장 CronCreate/CronDelete/CronList 사용)

5.1 정기 작업 생성: /harness cron "<cron 표현식>" [mode]

5.2 정기 작업 조회: /harness cron list

5.3 정기 작업 삭제: /harness cron stop [job_id]

하위 프로세스 입력 메커니즘

파일 목록

관련 스킬

steipete/sag

steipete/oracle

steipete/peekaboo

mattpocock/design-an-interface

mattpocock/prototype

mattpocock/grill-me

5.1 정기 작업 생성: `/harness cron "<cron 표현식>" [mode]`

5.2 정기 작업 조회: `/harness cron list`

5.3 정기 작업 삭제: `/harness cron stop [job_id]`