ai-workflow-harness

A manual-first, approval-gated AI workflow harness for Claude Code, Codex, and Cursor.
(계획·승인·검증·기록으로 이어지는 AI 개발 하네스)

AI 코딩 에이전트와 반복 세션을 운영할 때 발생하는 범위 확장, 상태 불일치, 승인 없는 실행, 결정 기록 소실을 workflow 엔진 없이 문서와 명시적 gate만으로 제어한다.

Quick Start

[!NOTE]
fork / clone 후 신규/기존 프로젝트에 적용하려면:

1. §10 New Project Adoption 확인 — scaffold 명령 실행
2. docs/SCAFFOLD-ONBOARDING-GUIDE.md 따라 첫 세션 진행

이 repository 자체를 직접 project-local workspace로 전환하지 않는다.

Table of Contents

• Quick Start
• Prologue
• 1. What This Harness Is
• 2. Document Layers
• 3. Session Lifecycle
• 4. Work Selection And Routing
• 5. Approval Matrix
• 6. STATUS And Work File Rules
• 7. Command Map
• 8. Trigger And Cascade
• 9. Git Flow
• 10. New Project Adoption
• 11. Key Documents
• 12. Repository Layout
• 13. Validation
• 14. Origin
• 15. License

Prologue

Claude Code, Codex 등은 강력하지만 context를 잘못 관리하면 세션마다 동일한 설명을 반복하거나, 승인 없이 범위를 넘는 작업을 수행하거나, 결정 사항이 사라지는 문제가 생긴다.
이 하네스는 그 문제를 직접 경험하고, 실제 프로젝트에 적용하면서 발견한 마찰을 하나씩 문서와 규칙으로 굳힌 결과물이다.

여정 요약: 첫 commit 이후 340여 개의 commit을 거쳐 2026-05-24에 첫 안정화 기준선을 태그했다.

ai-workflow-v1.0.0 — Lightweight Manual-First AI Workflow Harness v1

이 tag가 가리키는 의미:

• 전역 행동 원칙, 실행 규칙, 상세 protocol, 사용자 매뉴얼이 계층화되었다.
• Claude, Codex, Cursor, prompts, scaffold가 같은 핵심 계약을 참조한다.
• STATUS.md는 dashboard, Work 파일은 작업 단위 SSoT로 분리되어 관리된다.
• Approval Matrix로 scope, state update, commit gate가 하나의 기준으로 정리되었다.
• Multi Active Work 지원 — Work 파일 단위 SSoT로 컨텍스트를 분리해 여러 작업을 병렬 추적한다.

이후 변경은 v1.0을 더 키우기보다 실제 사용 중 발견된 반복 실패를 기준으로 작게 보정하는 방향으로 진행할 예정이다.

환경 지원: Primary macOS / Expected compatible Linux·WSL·Git Bash / Planned Windows native.
scaffold script와 일부 validation 예시는 bash, Unix-style path, python3를 전제한다. Windows native 지원은 HRN-032에서 추적한다.

1. What This Harness Is

AI Workflow Harness는 AI 세션을 감싸는 운영 구조다.
목표는 작업 상태, 승인 지점, 검증 결과, 결정 근거를 repo에 남겨 다음 세션과 다른 Agent가 이어받을 수 있게 하는 것이다.

핵심 원칙:

• Behavior Principles First — 속도보다 신중함과 안정성.
• Context Is Limited — 필요한 파일만 읽는다.
• Plan Before Implement — 실행 전 범위, 파일, 검증, 리스크, 되돌리기 비용을 보고한다.
• Approval Before Risk — scope 확장, 상태 변경, commit은 gate를 통과한다.
• Surgical Changes — 요청된 최소 범위만 바꾼다.
• State Is Repo-Visible — 다음 Agent가 기억 없이 이어받을 수 있어야 한다.

워크플로우 엔진 없이 문서와 명시적 gate만으로 제어한다. AI 파이프라인 자동화보다 AI와 협업하는 방식을 먼저 정립하는 단계에 맞는 도구다.

2. Document Layers

Harness 문서는 역할별로 계층이 나뉜다.
세션 시작 시 기본값으로 읽는 것은 BEHAVIOR-PRINCIPLES.md, AGENT-WORKFLOW.md, STATUS.md current sections뿐이다.
조건이 생길 때만 해당 문서를 추가 로드한다. 상세 routing 기준은 docs/AGENT-WORKFLOW.md 참조.

flowchart TD
    subgraph ENTRY ["Tool Entry Points"]
        CLAUDE["CLAUDE.md\nClaude"]
        AGENTS["AGENTS.md\nCodex"]
        CURSOR[".cursor/rules/*.mdc\nCursor"]
    end

    subgraph CANON ["Canonical Rules"]
        BP["docs/BEHAVIOR-PRINCIPLES.md\n전역 행동 원칙"]
        AW["docs/AGENT-WORKFLOW.md\n공통 실행 규칙"]
        HP["docs/HARNESS-PROTOCOL.md\n상세 protocol"]
        HQ["docs/HARNESS-QUICK-REFERENCE.md\n실행 quick reference"]
    end

    subgraph STATE ["State And Work"]
        STATUS["docs/STATUS.md\n현재 dashboard"]
        BACKLOG["docs/backlog/\n후보 작업"]
        WORK["docs/works/\nWork SSoT"]
        DR["docs/decisions/\nDecision Records"]
        ARCHIVE["docs/archive/\n완료 이력"]
    end

    subgraph SURFACE ["Reusable Surfaces"]
        COMMANDS[".claude/commands/\nClaude workflows"]
        RULES[".claude/rules/\npath-scoped guardrails"]
        CURSOR_RULES[".cursor/rules/\nCursor rules"]
        SKILLS[".agents/skills/\nCodex skills"]
        HOOKS[".codex/hooks.json\nCodex hooks"]
        PROMPTS["prompts/\nfallback/task templates"]
        SCRIPT["scripts/create-harness.sh\nproject scaffold"]
    end

    CLAUDE --> BP --> AW --> HP
    AGENTS --> BP
    AGENTS --> AW
    CURSOR --> BP
    CURSOR --> AW

    AW --> STATUS
    STATUS --> BACKLOG
    STATUS --> WORK
    WORK --> ARCHIVE
    STATUS --> DR

    HP --> HQ
    HP --> COMMANDS
    AW --> RULES
    AW --> CURSOR_RULES
    AW --> PROMPTS
    HP --> SCRIPT

    %% Layout hint: place reusable surfaces below the main document layers.
    ARCHIVE ~~~ COMMANDS
    DR ~~~ PROMPTS

    style BP fill:#f8d7da,stroke:#dc3545
    style AW fill:#ffeeba,stroke:#ffc107
    style HP fill:#d4edda,stroke:#28a745
    style STATUS fill:#d4edda,stroke:#28a745
    style WORK fill:#d4edda,stroke:#28a745

위에 포함되지 않은 User-facing docs(WORKFLOW-MANUAL.md, docs/retrospectives/, docs/troubleshooting/)는 평시 AI reading path에 포함하지 않고, 사용자가 매뉴얼 검토를 요청했거나 user-facing cascade가 필요할 때만 확인한다.

3. Session Lifecycle

모든 작업은 같은 state machine을 따른다.

flowchart TD
    INIT["INIT\n상태 확인"] --> PLAN["PLAN\n범위·파일·검증·리스크·되돌리기 비용"]
    PLAN --> APPROVAL{"APPROVAL\n사용자 승인?"}
    APPROVAL -- "수정 요청" --> PLAN
    APPROVAL -- "승인" --> EXECUTE["EXECUTE\n승인된 범위만 변경"]
    EXECUTE --> VALIDATE["VALIDATE\n테스트·diff·링크·scaffold 확인"]
    VALIDATE --> PASS{"통과?"}
    PASS -- "아니오" --> FAIL["FAIL\n원인·영향·복구 옵션 보고"]
    FAIL --> RECOVER["RECOVER\n계획 수정 또는 범위 축소"]
    RECOVER --> PLAN
    PASS -- "예" --> CHECKPOINT["CHECKPOINT\n필요한 상태 갱신·보고"]
    CHECKPOINT --> END["END\n/done 또는 다음 작업"]

    style INIT fill:#d4edda,stroke:#28a745
    style APPROVAL fill:#fff3cd,stroke:#ffc107
    style EXECUTE fill:#cce5ff,stroke:#004085
    style FAIL fill:#f8d7da,stroke:#dc3545
    style RECOVER fill:#fff3cd,stroke:#ffc107

1. /start 또는 intent recognition으로 현재 상태를 확인한다.
2. /pick, /work, /resume, /debug 중 맞는 흐름으로 진입한다.
3. Plan에는 Scope, Files, Verification, Risk, Reversal Cost를 포함한다.
4. 승인 후 실행한다.
5. 검증 실패 시 commit과 checkpoint를 만들지 않는다.
6. Work 완료는 /close, 세션 요약은 /done으로 분리한다.

4. Work Selection And Routing

STATUS.md는 dashboard이고, 모든 후보를 담는 backlog가 아니다.

flowchart TD
    NEW["새 요청·아이디어·버그"] --> NOW{"지금 착수?"}

    NOW -- "예" --> ACTIVE["STATUS.md Active Work\n현재 진행 pointer"]
    ACTIVE --> WORK["/work\n계획 수립"]
    WORK --> WORKFILE["docs/works/{category}\n{ID}-*.md"]

    NOW -- "아니오" --> TYPE{"성격"}
    TYPE -- "Product track / Phase 기능" --> PHASE["docs/backlog/PHASE{n}.md"]
    TYPE -- "Harness / workflow" --> HARNESS["docs/backlog/HARNESS.md"]
    TYPE -- "다음 세션 단기 후보" --> NEXT["STATUS.md Next Actions"]
    TYPE -- "결정 필요" --> OQ["STATUS.md Blockers/OQ"]

    OQ --> DR{"DR-worthy?"}
    DR -- "예" --> DECISION["docs/decisions/DR-*.md"]
    DR -- "아니오" --> OQ

    style ACTIVE fill:#d4edda,stroke:#28a745
    style WORKFILE fill:#d4edda,stroke:#28a745
    style OQ fill:#fff3cd,stroke:#ffc107
    style DECISION fill:#f8d7da,stroke:#dc3545

5. Approval Matrix

실행 전 승인, 상태 변경 승인, commit 전 승인을 하나의 기준으로 묶는다.

• Quick Mode는 Product track surface의 작고 명확한 L1 작업에 한정한다.
• Harness/workflow surface(entrypoint/workflow/protocol/command/rule/prompt/scaffold/status)를 건드리면 기본 L2로 다룬다.
• 멀티 Active Work 환경에서는 모든 state-change proposal에 대상 Work ID를 명시한다.

AI가 반드시 멈춰야 하는 경우:
승인된 scope 밖 파일을 고쳐야 할 때 / STATUS Active Work pointer를 추가·제거해야 할 때 / Work를 Done 처리해야 할 때 / commit하려 할 때 / validation 실패 후 복구 방향을 바꿔야 할 때.

6. STATUS And Work File Rules

STATUS.md와 Work 파일의 역할은 다르다.

flowchart LR
    STATUS["STATUS.md\ndashboard\n현재 상태·pointer"]
    WORK["Work file\nSSoT\nPlan·Done Criteria·Verification·Checkpoints·Discovery"]
    BACKLOG["backlog\n후보 pool"]
    ARCHIVE["archive\n완료 이력"]

    BACKLOG -->|"/work 승인"| STATUS
    STATUS -->|"pointer"| WORK
    WORK -->|"checkpoint/discovery"| WORK
    WORK -->|"/close Done"| STATUS
    WORK -->|"archive 승인"| ARCHIVE

    style STATUS fill:#d4edda,stroke:#28a745
    style WORK fill:#d4edda,stroke:#28a745
    style ARCHIVE fill:#e2e3e5,stroke:#6c757d

STATUS.md — 현재 중심으로 가볍게 유지한다.

Work File Lifecycle

stateDiagram-v2
    [*] --> Active: /work 승인 후 Work 파일 생성
    Active --> Done: /close 승인
    Done --> Archived: archive 승인
    Archived --> [*]
    Done --> [*]: 재개 금지 — 후속 작업으로 분리

    note right of Active
        checkpoint / discovery
    end note

/close와 /done은 다르다.

7. Command Map

Claude slash command는 Codex 역시 같은 의도로 수행한다.

Health 체크 권장 cadence:

8. Trigger And Cascade

Trigger는 AI가 자동 실행하는 명령이 아니라 제안 조건이다. 사용자 승인 전에는 파일을 바꾸지 않는다.
상세 trigger ID(T-번호)와 cascade 매핑은 docs/HARNESS-PROTOCOL.md 참조.

핵심 cascade 규칙:

• canonical workflow가 바뀌면 tool-specific, user-facing, scaffold surface를 함께 확인한다.
• command/rule/prompt/entrypoint가 바뀌면 Claude/Codex/Cursor alignment를 확인한다.
• scripts/create-harness.sh 또는 canonical workflow가 바뀌면 dry-run과 temp scaffold를 검증한다. scaffold script가 없는 repository는 Skipped / Not Applicable로 보고한다.
• commit 또는 PR 전에는 STATUS Finalization(T15)과 Tracking Finalization(T16)으로 docs/STATUS.md, backlog, Work, DR tracker의 최종 반영 여부를 판정한다.

9. Git Flow

이 repository의 기본 branch 전략은 Gitflow다. 상세 절차와 예외는 docs/GIT-WORKFLOW.md를 SSoT로 둔다.

main
 └── develop
      └── feature/*

• feature 작업은 develop 기준으로 branch를 만든다. feature → develop 병합은 PR로만 한다.
• develop → main PR은 의미 있는 패치가 완료된 release-ready 상태일 때만 생성한다. PR 생성 전 docs/GIT-WORKFLOW.md §3-1 Public Clean Baseline Gate를 수행하고 결과를 PR body에 남긴다.
• main PR merge 후에는 main을 pull하고 develop에 origin/main을 merge한 뒤 push하여 동기화한다.
• commit 전에는 validation 결과, diff summary, 제안 commit message를 보고하고 별도 승인을 받는다.

10. New Project Adoption

새 프로젝트 또는 기존 프로젝트에 적용할 때는 scripts/create-harness.sh를 사용한다.
기본 profile은 framework를 가정하지 않는 generic이다.

권장 경로: 이 repository를 clone한 뒤 직접 project-local workspace로 전환하지 않는다.
이 repository는 harness source로 유지하고, 실제 적용 대상은 아래 scaffold 명령으로 별도 target directory에 생성한다.
scaffold 후 첫 세션은 docs/SCAFFOLD-ONBOARDING-GUIDE.md를 따라 진행한다.

# 신규 프로젝트
scripts/create-harness.sh my-app
scripts/create-harness.sh my-app /path/to/my-app

# 기존 프로젝트에 추가
scripts/create-harness.sh --existing my-app /path/to/existing-project

# Spring Boot example pack 포함
scripts/create-harness.sh --profile spring-boot my-app /path/to/my-app

# dry-run (파일 생성 없이 확인)
scripts/create-harness.sh --dry-run my-app

target-dir 생략 시 temp/<project-name>/에 생성된다.

flowchart TD
    A(["Adoption 시작"]) --> B{"신규 / 기존?"}

    B -- "신규 repo" --> C["create-harness.sh my-app\n또는 my-app /path"]
    B -- "기존 repo" --> D["create-harness.sh --existing my-app /path"]

    C --> E["scaffold 생성\nSTATUS.md · BOOTSTRAP.md\nbacklog · decisions · works\ncommands · rules · prompts"]
    D --> F["AI: 코드베이스 읽기\n파일 내용 제안 → 사용자 승인"]
    F --> E

    E --> G["/start 첫 세션"]

    G --> H{"STATUS.md Next Actions에\nbootstrap pointer 있음?"}

    H -- "없음" --> I["일반 세션 시작\n/pick → /work → /close"]
    H -- "있음" --> J["BOOTSTRAP.md 로드\n§8 First Prompt 사용"]

    J --> K["Bootstrap Onboarding\nProduct Definition → Project Initialization\n→ Phase 1 Backlog"]

    K --> L["STATUS.md Next Actions에서\nbootstrap pointer 제거"]

    L --> I

    style J fill:#fff3cd,stroke:#ffc107
    style K fill:#cce5ff,stroke:#004085
    style L fill:#d4edda,stroke:#28a745
    style I fill:#d4edda,stroke:#28a745

Bootstrap onboarding은 Product Definition과 docs/PLAN-SUMMARY.md Implementation Baseline을 먼저 채운 뒤 Phase 1 backlog를 도출한다.
Implementation Baseline이 비어 있으면 feature candidate은 Not Ready로 보고하고 Project Initialization을 첫 P1 후보로 제안한다.
기존 프로젝트에 적용할 때는 코드베이스를 먼저 읽고 파일 내용을 제안하게 한다. 승인 전 파일을 채우지 않는다.

이 Repository에서 작업

Claude Code 세션: /start 실행 또는 docs/STATUS.md 확인.
Codex 세션: AGENTS.md를 읽고 /start intent로 현재 상태를 확인한다.

# pre-commit hook 선택적 설치 (일반 사용이나 scaffold 적용에는 불필요)
sh tools/git-hooks/install.sh

11. Key Documents

Language Policy

docs/decisions/DR-007-language-policy.md — 대부분의 문서는 한국어, Agent Core 문서는 영어.

Entry Points

Workflow Core

State & Tracking

Reference & Maintenance

12. Repository Layout

.
├── AGENTS.md                         # Codex 진입점
├── CLAUDE.md                         # Claude Code 진입점
├── .agents/
│   └── skills/                       # Codex skill 파일
├── .claude/
│   ├── commands/                     # slash command 정의 (/start, /work, /close 등)
│   └── rules/                        # path-scoped rule mirror
├── .codex/
│   └── hooks.json                    # Codex hook 설정
├── .cursor/
│   └── rules/                        # Cursor rule mirror
├── docs/
│   ├── BEHAVIOR-PRINCIPLES.md        # 전역 행동 원칙
│   ├── AGENT-WORKFLOW.md             # 공통 workflow·Approval Matrix
│   ├── HARNESS-PROTOCOL.md           # 상세 protocol 레퍼런스
│   ├── HARNESS-QUICK-REFERENCE.md    # 세션 실행 규칙 빠른 참조
│   ├── HARNESS-STRUCTURE.md          # harness 구조 시각화
│   ├── HARNESS-MAINTAINER-GUIDE.md   # 유지보수·convention 가이드
│   ├── SCAFFOLD-BOOTSTRAP.md         # scaffold boot sequence 설계 기준
│   ├── GIT-WORKFLOW.md               # Git 브랜치·커밋 전략
│   ├── STATUS.md                     # 현재 dashboard
│   ├── PLAN.md                       # 프로젝트 방향·roadmap
│   ├── PLAN-SUMMARY.md               # 세션 컨텍스트 요약
│   ├── WORKFLOW-MANUAL.md            # 사용자용 workflow manual
│   ├── backlog/                      # 후보 작업 목록
│   ├── decisions/                    # Decision Records
│   ├── retrospectives/               # 회고 기록
│   └── works/                        # Work 파일 (작업 단위 SSoT)
├── prompts/                          # portable prompt 템플릿
├── scripts/
│   └── create-harness.sh             # scaffold script
└── tools/
    └── git-hooks/                    # pre-commit hook

13. Validation

git diff --check
bash -n scripts/create-harness.sh
./scripts/create-harness.sh --dry-run --profile generic sample /tmp/sample

14. Origin

이 저장소는 kyungseo/base-msa-template에서
Git history를 보존한 채 추출되었다. 하네스는 Spring Boot MSA template을 hardening하는 과정에서 형성되었으며,
현재는 AI Workflow Harness 자체에 집중한다.

15. License

LICENSE 참조.