coding-harness

name	coding-harness
description	Hermes coding harness - Plan -> TODO -> Execute -> Verify -> Debug loop. Completely standalone. No external skill dependencies. Uses only Hermes native tools: file, terminal, code_execution, session_search, memory, delegation.
version	1.0.0
author	tmdgusya

Hermes Coding Harness

Hermes의 코딩 작업 특화 활성화 스킬입니다. 코딩 작업이 감지되면 자동으로 계획을 세우고, TODO를 관리하며, 실행→검증 루프를 돌립니다.

핵심 특징: 외부 스킬 의존성 없이 standalone으로 동작합니다.

---

트리거 조건

사용자 입력이 아래 패턴을 맞을 때 트리거된다:

1. 패턴 감지:

   • "구현해줘", "만들어줘", "코드 작성", "기능 추가", "버그 수정", "리팩토링", "디버깅"
   • "진단위 테스트 작성", "배포해줘", "CI/CD 설정"
   • 파일 경로 패턴: */, *.py, *.js, *.ts, src/, app/, lib/, cmd/

2. 기술 스택 언급:

   • FastAPI, Django, Flask, React, Next.js, Vue, Svelte
   • Rust (Actix, Axum), Go (Gin, Echo), Node.js (Express, NestJS)
   • 데이터베이스 연동, API 설계, 인증/인가 구현

3. 파일 확장자:

   • .py, .js, .ts, .jsx, .tsx, .rs, .go, .java, .kt, .scala
   • .c, .cpp, .h, .cs, .rb, .php, .swift

트리가되면 아래 6단계 루프를 자동으로 진입한다.

---

6-Stage Loop

Stage 1: DETECT — 코딩 작업 감지

사용자 입력을 분석하여 코딩 작업 여부를 판단한다.

판단 기준:

• 요청에 코드 작성, 수정, 추가, 삭제가 포함되어 있는가?
• 프로젝트 파일 구조 변경이 필요한가?
• 의존성 설치, 빌드, 테스트 실행이 필요한가?

결과:

• 코딩 작업이 맞다고 판단되면 Stage 2로 진행
• 코딩 작업이 아니면 일반 대화 모드로 돌아간다

---

Stage 2: PLAN — 계획 수립 (내장)

작업 디렉토리에 PLAN.md를 생성한다.

수행 단계:

1. session_search 도구로 과거 세션에서 유사한 작업 패턴 검색
2. file 도구로 기존 코드베이스 구조 탐색
3. memory 도구로 사용자의 코딩 스타일/선호 참조
4. 다음 템플릿으로 PLAN.md 작성:

# [작업명] 구현 계획

> **Generated by coding-harness**

**Goal:** [한 문장 목표]

**Tech Stack:** [사용 기술]

**Work Scope:**
- **In scope:** [포함 내용]
- **Out of scope:** [제외 내용]

---

## 파일 구조 맵핑

[생성/수정될 파일 목록]

---

## 단계

1. [단계명] — [구체적 작업]
2. [단계명] — [구체적 작업]
3. [단계명] — [구체적 작업]
...

---

## 검증 전략
- **Build:** [빌드 명령어]
- **Test:** [테스트 명령어]
- **Lint:** [린트/포맷팅 명령어]

규칙:

• 한 문장 Goal
• 3~7개의 단계 (더 크면 단계를 더 세분)
• 각 단계에는 구체적인 작업 내용 기술
• Out of scope를 명확히 기술

---

Stage 3: TODO — 작업 분해 (내장)

PLAN.md를 기반으로 TODO.md를 생성하여 단계별 상태를 관리한다.

수행 단계:

1. file 도구로 PLAN.md 읽기
2. PLAN.md의 단계를 TODO 항목으로 변환
3. TODO.md 작성:

# [작업명] TODO

> **Generated by coding-harness**
> **Status:** [진행중 | 완료 | 방어금]

## 준비 (Planning)
- [x] 요구사항 분석
- [x] 기존 코드베이스 탐색
- [x] 계획 수립 (PLAN.md)

## 구현 (Implementation)
- [ ] Task 1: [단계명]
  - Files: [파일 목록]
  - Action: [구체 작업]
- [ ] Task 2: [단계명]
  - Files: [파일 목록]
  - Action: [구체 작업]
...

## 검증 (Verification)
- [ ] 빌드/테스트 실행: [명령어]
- [ ] 린트/포맷팅 검사: [명령어]
- [ ] 후토검사: 결과물 검토

## 마무리 (Done)
- [ ] 최종 결과물 정리
- [ ] 프롬프트 최적화 회고 기록

규칙:

• 각 태스크는 하나의 파일만 수정 (충돌 방지)
• 파일 의존성이 있는 경우 순차 실행
• 의존성이 없는 태스크는 delegation 도구로 병렬 가능

---

Stage 4: EXECUTE — 실행 (내장)

TODO.md의 항목을 하나씩 실행한다.

사용 도구:

• file — 코드 작성/수정
• terminal — 빌드/테스트/패키지 설치, git 조작
• code_execution — 스크립트 실행, 데이터 처리, 검증
• delegation — 병렬 작업이 필요할 때만 사용

실행 규칙:

1. 한 번에 하나의 파일만 수정 (충돌 방지)
2. 실행 전후로 file 도구로 TODO.md 상태 업데이트
3. 각 단계 완료 시 terminal로 git commit 권장
4. 오류 발생 시 Stage 5(DEBUG)로 전환

TODO 상태 업데이트 패턴:

- [ ] Task N: [작업명]   → 실행 전
- [~] Task N: [작업명]   → 실행 중
- [x] Task N: [작업명]   → 완료
- [!] Task N: [작업명]   → 실패 (DEBUG 로 전환)

---

Stage 5: VERIFY — 검증 (내장)

모든 실행 완료 후 검증을 실행한다.

수행 단계:

1. terminal 도구로 scripts/verify.sh를 호출하거나 직접 검증 명령 실행
2. PLAN.md의 검증 전략 섹션을 참조하여 검증
3. 결과를 TODO.md에 기록

프로젝트 타입별 검증 명령:

타입	검증 명령
Python	pytest -q, ruff check ., mypy .
Node.js	npm test, npm run lint
Rust	cargo test --quiet, cargo clippy --quiet
Go	go test ./..., go vet ./...
Makefile	make test
Docker	docker build .

실패 시:

• 오류 메시지와 실패한 부분을 TODO.md에 기록
• Stage 6(DEBUG)로 전환

---

Stage 6: DEBUG — 디버깅 (내장 4단계)

VERIFY 실패 시 실행하는 시스템적 디버깅 루틴. 외부 systematic-debugging 스킬을 호출하지 않는다.

Phase 1: Understand (이해)

1. 오류 메시지를 정확히 읽기
2. 실패한 파일과 라인 번호를 기록
3. 오류 타입 분류:
   • SyntaxError / CompileError: 문법 오류
   • ImportError / ModuleNotFoundError: 의존성 오류
   • AssertionError / Test Failure: 로직 오류
   • RuntimeError / Exception: 런타임 오류
4. 최근 변경사항과 연관성 분석 (terminal: git diff --name-only)

Phase 2: Reproduce (재현)

1. 오류를 재현할 수 있는 최소 명령어 찾기
2. terminal 도구로 해당 명령어 실행하여 오류 확인
3. 오류가 재현되는지 기록 (체크박스: [ ] → [x])

Phase 3: Isolate (쫎어내기)

1. 오류 원인을 좁혀가기:
   • 가장 최근에 수정한 파일부터 역순으로 점검
   • 의존성 변경 여부 확인 (package 추가, 버전 업 등)
   • 환경 변수/설정 파일 변경 여부 확인
2. file 도구로 관련 파일 내용 읽기
3. 중간 결과물을 출력하여 상태 확인 (code_execution)

Phase 4: Fix & Verify (수정 & 확인)

1. 원인을 수정 (file 도구)
2. Phase 2의 재현 명령어로 다시 실행 (terminal)
3. 통과할 때까지 Phase 1~4 반복
4. 수정 완료 시 TODO.md에 디버깅 기록 추가:

   ## Debug Log
   - [x] Issue: [오류 설명]
   - [x] Root Cause: [원인]
   - [x] Fix: [수정 내용]
   - [x] Verification: [확인 명령어] → PASS
   

5. 디버깅 완료 후 Stage 4(EXECUTE)로 돌아가야 할 항목 계속

---

Self-Evolution

매 코딩 작업 완료 후 다음을 memory 도구로 기록한다:

[coding-harness] 패턴 학습 중...

- 작업 타입: [Python/FastAPI | React/Next.js | Rust | Go | ...]
- 계획 단계 수: [N]
- 디버깅 회수: [N]
- 성공 패턴:
  - [잘 된 것]
- 실패 패턴:
  - [안 된 것]
- 최적화 점:
  - [다음 번에 해야 할 것]

이들은 다음 세션의 PLAN 단계에서 참조된다.

---

연동 금지 규칙

이 스킬은 외부 스킬을 호출하지 않는다:

금지 항목	이유
❌ plan-crafting 스킬 호출	내장 PLAN 로직이 있음
❌ todo 스킬 호출	내장 TODO 관리 있음
❌ systematic-debugging 스킬 호출	내장 DEBUG 루틴 있음
❌ 외부 스킬 파일 직접 읽기	standalone 원칙 파괴

허용 도구:

• ✅ file
• ✅ terminal
• ✅ code_execution
• ✅ session_search
• ✅ memory
• ✅ delegation (병렬 필요시에만)

---

사용 예시

사용자 입력

FastAPI 프로젝트에 JWT 인증 미들웨어를 구현해줘.

Harness 동작

DETECT: 코딩 작업 감지 ("구현", "FastAPI")

PLAN: PLAN.md 생성

Goal: FastAPI JWT 인증 미들웨어 구현
Tech: FastAPI, PyJWT
Steps:
1. pyproject.toml 의존성 추가
2. middleware/auth.py 구현
3. tests/test_auth.py 작성
4. pytest 실행

TODO: TODO.md 생성

## 구현
- [ ] pyproject.toml 의존성 추가
- [ ] middleware/auth.py 구현
- [ ] tests/test_auth.py 작성

EXECUTE: 각 항목 실행

• file: pyproject.toml 수정
• terminal: pip install pyjwt
• file: middleware/auth.py 생성
• file: tests/test_auth.py 생성

VERIFY:

$ pytest tests/test_auth.py -v
============================== 3 passed ==============================

DEBUG: 통과 — 시도 안 함

LEARN: memory에 패턴 기록