AI Workflow Harness로 정리하는 승인 기반 AI 협업 워크플로우

이 글은 ai-workflow-harness 프로젝트를 중심으로, 여러 AI 도구를 실제 개발 프로젝트에 안정적으로 적용하기 위한 manual-first, approval-gated 워크플로우 구조를 정리한 글입니다.
AI를 활용해 작업을 진행하다 보면 범위가 커지거나, 승인 없이 파일이 변경되거나, 중요한 결정 근거가 대화 속에만 남는 문제가 자주 발생합니다. ai-workflow-harness는 이런 문제를 계획, 승인, 검증, 기록이라는 명확한 절차로 통제할 수 있도록 설계된 구조입니다.
이 글에서는 이 harness의 개념적 배경, 핵심 원칙, 구조, 적용 방법을 단계별로 살펴봅니다.

반응형

---

ai-workflow-harness란 무엇인가

ai-workflow-harness는 AI가 프로젝트 안에서 일하는 방식을 표준화한 source repository입니다.
중요한 점은 이 저장소가 곧바로 제품 코드가 들어가는 템플릿이 아니라는 것입니다. 실제 프로젝트에는 이 저장소를 기반으로 scaffold 결과물을 생성해 적용하고, 각 프로젝트가 자신의 상태 파일과 기록을 채워 나가게 됩니다.

이 구조의 목적은 단순합니다.

• AI가 작업 범위를 넘어서지 않도록 통제
• 승인되지 않은 변경 방지
• 작업 상태와 결정 근거를 저장소 안에 명확히 남김
• 여러 AI 도구와 세션이 같은 규칙과 상태를 공유하도록 유도

---

왜 이런 구조가 필요한가

AI와 여러 세션에 걸쳐 작업하다 보면 다음과 같은 문제가 반복됩니다.

• 작업 범위가 점점 커지지만 통제되지 않음
• 사용자가 승인하지 않은 파일 변경 발생
• 중요한 판단 근거가 대화 로그에만 남아 다음 세션에서 사라짐
• 다른 AI 도구가 이전 맥락을 알 수 없음

ai-workflow-harness는 별도의 workflow engine 없이도 이런 문제를 해결하기 위해, 사람이 읽고 승인할 수 있는 문서와 상태 파일을 중심으로 한 운영 방식을 채택합니다.

---

핵심 원칙 정리

이 harness를 관통하는 원칙은 명확합니다.

Plan before implement

실행 전에 반드시 작업 범위, 변경 파일, 검증 방법, 리스크, 되돌릴 비용을 정의합니다.

Approval before risk

범위 확장, 상태 변경, 커밋은 승인 단계를 통과해야만 진행됩니다.

State is repo-visible

다음 AI가 대화 기억 없이도 이어서 작업할 수 있도록 상태를 저장소에 남깁니다.

Surgical changes

승인된 범위만 정확하게 수정합니다. 불필요한 확장은 허용하지 않습니다.

---

Repository 구조의 큰 그림

처음에는 모든 파일을 이해할 필요는 없습니다. 전체 구조는 다음 여섯 가지 역할로 나뉩니다.

1. Entry points
   Claude Code, Codex, Cursor 등 AI 도구별 시작 지점
2. Shared operating rules
   모든 도구가 공통으로 따라야 할 규칙
3. Canonical workflow
   실제 절차의 단일 기준(Single Source of Truth)
4. Adapters
   각 AI 도구가 canonical 절차를 호출하도록 연결
5. State files
   작업 상태와 결정 근거를 저장소에 기록
6. Scaffold
   이 구조를 다른 프로젝트에 설치하는 스크립트

이 중 핵심 규칙의 권위는 README가 아니라 docs/BEHAVIOR-PRINCIPLES.md, docs/AGENT-WORKFLOW.md, skills/workflow/에 있습니다.

---

프로젝트에 적용하는 방법

새 프로젝트나 기존 프로젝트에 harness를 적용할 때는 scripts/create-harness.sh를 사용합니다.

새 프로젝트에 적용

scripts/create-harness.sh my-app /path/to/my-app

기존 프로젝트에 추가

scripts/create-harness.sh --existing my-app /path/to/existing-project

주요 옵션

• --with-optional : optional pack 포함
• --workflow source-gitflow : source repository의 Gitflow 정책 적용
• --dry-run : 파일 생성 없이 변경 내용 확인
• --check : scaffold된 파일과 source 간 drift 확인

중요한 점은 이 repository 자체를 project-local workspace로 사용하지 않는 것입니다. 반드시 scaffold를 통해 별도의 project directory에 적용해야 합니다.

---

Scaffold 이후 첫 세션 흐름

scaffold가 끝나면 생성된 프로젝트 디렉터리에서 /session-start로 첫 세션을 시작합니다.
이후 docs/STATUS.md와 docs/BOOTSTRAP.md를 채우며 다음 내용을 정리합니다.

• Product Definition
• Implementation Baseline
• Phase 1 backlog

이 과정이 끝나야 AI가 해당 프로젝트의 맥락을 이해한 상태로 작업을 시작할 수 있습니다.

---

Workflow의 상태 머신 구조

모든 작업은 동일한 상태 머신을 따릅니다.

INIT → PLAN → APPROVAL → EXECUTE → VALIDATE → CHECKPOINT → END
                 ↑                     ↓
              RECOVER ← FAIL ←──────────

기본 흐름은 다음과 같습니다.

1. /session-start로 현재 상태 확인
2. 작업 성격에 따라 /work-select, /work-plan 등으로 진입
3. Plan 단계에서 Scope, Files, Verification, Risk, Reversal Cost 정의
4. 사용자 승인 후 실행
5. 검증 실패 시 checkpoint나 commit 생성 없음
6. 완료 시 /work-close, 요약은 /session-summary

---

Approval Matrix와 변경 통제

Approval Matrix는 다음 세 가지를 하나의 기준으로 묶습니다.

• 실행 전 승인
• 상태 변경 승인
• 커밋 전 승인

작고 명확한 작업만 Quick Mode로 허용되며, workflow나 harness 구조를 건드리는 작업은 기본적으로 더 높은 승인 레벨을 요구합니다.

AI는 조건이 충족돼도 자동으로 파일을 수정하지 않습니다.
변경이 필요하다고 판단되면 먼저 제안하고, 사용자 승인 후에만 수정이 이루어집니다.

---

728x90

ai-workflow-harness는 AI를 더 똑똑하게 만드는 도구라기보다, AI를 신뢰할 수 있는 협업 파트너로 만들기 위한 운영 프레임워크에 가깝습니다.

• AI 작업이 기록으로 남고
• 승인되지 않은 변경을 막으며
• 여러 AI 도구가 같은 맥락에서 일할 수 있게 하고
• 사람이 최종 통제권을 유지합니다

AI 활용이 점점 복잡해지는 환경에서, 이와 같은 명시적이고 문서화된 워크플로우는 앞으로 더 중요한 기준이 될 가능성이 큽니다.
특히 팀 단위 개발이나 장기 프로젝트에서는, ai-workflow-harness와 같은 접근 방식이 AI 협업의 안정성을 크게 높여줄 수 있습니다.

300x250

https://github.com/kyungseo/ai-workflow-harness?fbclid=IwY2xjawSVhRVleHRuA2FlbQIxMQBzcnRjBmFwcF9pZBAyMjIwMzkxNzg4MjAwODkyAAEeKr2KZRhCrIHepqzCqeDXjp7wC9PN2-UvAbZ1p05kAe8ZZbrsWkbad_gvPQw_aem_l_bne2FbfGat3FkcHbZM2Q

GitHub - kyungseo/ai-workflow-harness: A manual-first, approval-gated AI workflow harness for Claude Code, Codex, and Cursor. (