범용 AI 프로젝트 하네스 설계 방법론

범용 AI 프로젝트 하네스 설계 방법론

AI에게 작업을 한 번 요청하는 방식에서 벗어나, 계획·실행·검증·릴리스를 반복 가능하고 감사 가능한 공정으로 만드는 방법

1. 문서의 목적

이 문서는 웹서비스, 모바일 앱, 게임, 영상, 데이터 파이프라인, 문서 제작 등 서로 다른 프로젝트에 적용할 수 있는 AI 작업 하네스의 설계 원칙과 구현 절차를 정의한다.

여기서 하네스는 모델 자체가 아니다. 모델이 프로젝트 안에서 일관되게 작업하도록 다음 요소를 제공하는 실행 구조다.

• 작업 순서와 판단 규칙
• 파일 기반의 영속 상태
• 단계별 입력·출력 계약
• 반복 작업을 처리하는 결정론적 스크립트
• 자동 검증과 사람의 승인 게이트
• 재개, 부분 수정, 실패 복구 규칙
• 최종 결과물 패키징 방식

핵심 목표는 “좋은 결과를 한 번 얻는 것”이 아니라 “같은 절차로 계속 결과를 만들고, 실패 지점을 찾고, 필요한 부분만 다시 실행할 수 있게 하는 것”이다.

2. 핵심 원칙

2.1 모델과 하네스의 책임을 분리한다

모델에 맡길 작업:

• 요구사항 해석
• 설계 대안 비교
• 창의적 기획과 콘텐츠 작성
• 코드와 설정 초안 작성
• 시각 결과 판단
• 실패 원인 설명과 수정안 선택

스크립트에 맡길 작업:

• 폴더와 상태 파일 생성
• 파일명과 스키마 검사
• 빌드, 테스트, 린트 실행
• 해시와 중복 검사
• 결과물 등록과 복사
• 단계 전이 조건 확인
• 배포 패키지 조립

판단이 필요한 일은 모델에, 동일한 입력에서 동일한 결과가 나와야 하는 일은 스크립트에 둔다.

2.2 채팅이 아니라 파일을 진실의 원천으로 삼는다

AI 대화는 실행 인터페이스이고, 프로젝트 파일이 영속 기억이다. 다음 실행에서 이전 채팅을 사용할 수 없더라도 state.json, 명세, 결과물, 검증 보고서만 읽으면 이어서 작업할 수 있어야 한다.

2.3 단계마다 명시적인 계약을 둔다

각 단계에는 반드시 다음 네 가지가 있어야 한다.

1. 입력: 무엇을 읽어야 하는가
2. 작업: 무엇을 결정하거나 생성하는가
3. 출력: 어떤 파일을 만들어야 하는가
4. 게이트: 무엇을 통과해야 다음 단계로 갈 수 있는가

2.4 생성과 검증을 분리한다

결과를 만든 주체가 스스로 “완료”라고 선언하는 것만으로 릴리스하지 않는다. 최소한 기계 검증과 의미 검증을 분리한다.

• 기계 검증: 파일 존재, 스키마, 빌드, 테스트, 해시, 누락 여부
• 의미 검증: 요구사항 충족, UX, 논리, 시각 품질, 업무 규칙
• 사람 승인: 비용, 배포, 삭제, 외부 전송 등 고위험 작업

2.5 전체 재실행보다 부분 재실행을 우선한다

수정 요청이 들어오면 가장 먼저 영향을 받는 단계로 상태를 되돌리고, 그 단계와 하위 결과물만 다시 만든다. 상위의 승인된 명세와 자산은 보존한다.

3. 전체 구조

flowchart TD
    U["사용자 요청"] --> S["하네스 스킬과 프로젝트 규칙 로드"]
    S --> R["현재 상태와 기존 결과물 확인"]
    R --> P["계획 및 명세"]
    P --> I["구현 또는 생성"]
    I --> V1["기계 검증"]
    V1 -->|실패| F["실패 범위 판정"]
    F --> I
    V1 -->|통과| V2["의미 및 품질 검증"]
    V2 -->|수정 필요| F
    V2 -->|승인| B["패키징 및 릴리스"]
    B --> C["상태와 연속성 기록"]

권장 기본 상태 전이는 다음과 같다.

initialized
  → specified
  → planned
  → implemented
  → machine_validated
  → quality_validated
  → packaged
  → released

프로젝트 성격에 따라 상태 이름은 바꿀 수 있지만, 생성 전·생성 후·검증 후·릴리스 후를 구분해야 한다.

4. 권장 디렉터리 구조

project-root/
├── AGENTS.md
├── .codex/
│   └── skills/
│       └── project-harness/
│           ├── SKILL.md
│           ├── agents/
│           │   └── openai.yaml
│           ├── scripts/
│           │   ├── init_work.py
│           │   ├── advance_stage.py
│           │   ├── register_artifact.py
│           │   ├── validate_work.py
│           │   ├── build_release.py
│           │   └── finalize_release.py
│           ├── references/
│           │   ├── production-contract.md
│           │   ├── validation-rules.md
│           │   └── domain-rules.md
│           └── assets/
│               └── release-template/
├── _workspace/
│   ├── state.json
│   ├── 00_input/
│   ├── 01_specification/
│   ├── 02_plan/
│   ├── 03_output/
│   ├── 04_validation/
│   ├── 05_assembly/
│   └── RELEASE/
└── application-source/

역할은 다음과 같이 나눈다.

위치	역할
AGENTS.md	저장소 전체에서 지켜야 할 경계와 안전 규칙
SKILL.md	AI가 따라야 할 핵심 실행 절차
references/	필요할 때만 읽는 상세 업무 규칙과 스키마
scripts/	반복 가능하고 결정론적인 작업
assets/	결과물에 복사해서 사용할 템플릿과 정적 자산
_workspace/	실행 상태, 중간 결과, 검증 기록, 릴리스 패키지

중간 결과를 Git에 포함할 필요가 없다면 _workspace/를 .gitignore에 추가한다. 다만 운영상 보존해야 하는 감사 기록은 별도 저장소나 아티팩트 스토리지로 내보낸다.

5. 하네스 설계 절차

5.1 반복 가능한 실제 요청을 수집한다

먼저 사용자가 하네스에 어떤 문장으로 일을 시킬지 정의한다.

예시:

• “새 기능을 요구사항부터 구현하고 테스트해줘.”
• “이전 작업을 이어서 릴리스 패키지를 만들어줘.”
• “UI만 수정하고 영향받는 테스트를 다시 실행해줘.”
• “실패한 검증 단계부터 재개해줘.”

최소한 신규 작업, 이어서 하기, 부분 수정, 검증, 릴리스 요청을 각각 하나씩 준비한다.

5.2 작업을 4~7개의 생산 단계로 압축한다

사람의 직책이나 페르소나 수를 늘리기보다 실제 의존성 기준으로 단계를 나눈다.

범용 기본형:

단계	핵심 결과
입력	요청, 제약, 기존 시스템 상태
명세	범위, 수용 조건, 비기능 요구사항
계획	설계, 작업 순서, 위험 요소
실행	코드, 콘텐츠, 데이터, 자산
검증	테스트 결과, 품질 판단, 알려진 제한
조립	실행 가능한 패키지 또는 배포 후보
릴리스	승인된 최종 결과와 이력

서로 독립적으로 실행할 수 없는 역할은 같은 단계에 둔다.

5.3 각 단계의 생산 계약을 작성한다

references/production-contract.md에 다음 형식으로 기록한다.

## implemented

- 입력
  - `01_specification/requirements.md`
  - `02_plan/implementation-plan.md`
- 필수 출력
  - 변경된 소스 코드
  - `03_output/artifacts.json`
- 자동 게이트
  - 대상 파일 존재
  - 금지 경로 변경 없음
  - 빌드 명령 성공
- 실패 시 복귀 단계
  - 계획 오류: `planned`
  - 구현 오류: `implemented`

5.4 상태 스키마를 설계한다

최소 상태 예시:

{
  "schema_version": 1,
  "project": "example-project",
  "work_id": "work-001",
  "stage": "implemented",
  "status": "in_progress",
  "mode": "standard",
  "created_at": "2026-01-01T00:00:00Z",
  "updated_at": "2026-01-01T01:00:00Z",
  "stages": {
    "specified": {"status": "completed"},
    "planned": {"status": "completed"},
    "implemented": {"status": "in_progress"}
  },
  "flags": [],
  "artifacts": []
}

상태에는 설명문 전체를 저장하지 않는다. 긴 판단과 결과는 Markdown 또는 JSON 아티팩트로 분리하고 상태 파일에는 경로와 진행 상태만 둔다.

5.5 아티팩트 등록 규격을 만든다

생성된 파일은 단순히 폴더에 놓는 것으로 끝내지 않고 manifest에 등록한다.

{
  "schema_version": 1,
  "work_id": "work-001",
  "artifacts": [
    {
      "file": "build/app.zip",
      "type": "release-package",
      "source_stage": "packaged",
      "sha256": "...",
      "metadata": {
        "platform": "linux-x64"
      }
    }
  ]
}

manifest에는 최소한 파일 경로, 종류, 생성 단계, 무결성 해시를 기록한다. 이미지, 영상, 데이터셋처럼 범위 정보가 필요한 경우 프레임, 장면, 레코드, 페이지 등의 논리 범위도 추가한다.

5.6 결정론적 스크립트를 구현한다

각 스크립트는 한 가지 책임만 갖게 한다.

init_work.py

• _workspace/ 구조 생성
• 새 work_id 결정
• 초기 state.json 생성
• 입력 브리프와 빈 manifest 생성
• 기존 작업이 있으면 무단 덮어쓰기 거부

advance_stage.py

• 목표 단계의 필수 결과물 검사
• 빈 파일과 잘못된 스키마 거부
• 선행 단계 완료 여부 확인
• 통과한 경우에만 상태 갱신

register_artifact.py

• 실제 파일 존재 여부 검사
• 경로가 허용된 작업공간 내부인지 확인
• 메타데이터와 해시 기록
• 중복 등록을 안전하게 갱신

validate_work.py

• 파일·스키마·범위·중복·해시 검사
• 프로젝트 빌드와 테스트 실행
• 결과를 validation.json으로 저장
• 통과한 검증 대상의 해시 기록

build_release.py

• 검증을 통과한 아티팩트만 복사
• 검증 이후 변경된 파일 거부
• 실행 가능한 배포 후보 조립
• 빌드에 포함된 파일 목록 기록

finalize_release.py

• 기계 검증 결과 확인
• 품질 보고서와 사람 승인 확인
• 릴리스 아티팩트 해시 재확인
• 최종 상태를 released로 전환

스크립트는 가능하면 다음 성질을 갖게 한다.

• 같은 입력으로 여러 번 실행해도 안전한 멱등성
• 실패 시 일부만 갱신하지 않는 원자성
• 오류 메시지에 실패 파일과 해결 조건 표시
• 절대 경로나 검증되지 않은 glob에 의존하지 않기
• 종료 코드 0은 성공, 그 외는 실패
• 사람이 읽을 출력과 기계가 읽을 JSON 결과를 분리

5.7 SKILL.md를 작성한다

SKILL.md는 장문의 업무 백과사전이 아니라 실행 라우터다. 핵심 절차만 두고 상세 규칙은 references/로 분리한다.

---
name: project-harness
description: Plan, implement, validate, resume, revise, package, and release work in this project. Use for new work, continuation, targeted revisions, validation, or release preparation.
---

# Project Harness

Use `_workspace/` as the durable source of truth.

## Start

1. Read `_workspace/state.json` when it exists.
2. Classify the request as new, continuation, targeted revision, validation, or release.
3. Read `references/production-contract.md` before changing state layout.
4. Initialize new work with `scripts/init_work.py`.

## Execute

1. Produce the required artifacts for the current stage.
2. Keep creative decisions in Markdown and machine state in JSON.
3. Run `scripts/advance_stage.py`; do not edit the stage manually.

## Validate and release

1. Run `scripts/validate_work.py`.
2. Fix only the failing stage and downstream artifacts.
3. Build with `scripts/build_release.py`.
4. Finalize only after machine and human gates pass.

스킬 설명에는 언제 자동으로 선택되어야 하는지 구체적으로 쓴다. 본문에는 이미 선택된 다음의 실행 방법만 기록한다.

5.8 AGENTS.md에 저장소 경계를 선언한다

# Repository instructions

- Use `.codex/skills/project-harness/SKILL.md` for work that creates, continues, revises, validates, packages, or releases project artifacts.
- Keep generated and intermediate artifacts under `_workspace/`.
- Use bundled scripts for initialization, registration, validation, and packaging.
- Preserve existing user changes and do not overwrite unrelated files.
- Do not mark work released until machine validation and required human approval pass.

여기에는 프로젝트 전체에서 항상 적용할 규칙만 둔다. 특정 단계에만 필요한 긴 규칙은 스킬 또는 참조 문서로 보낸다.

5.9 검증 계층을 구현한다

권장 검증 계층:

계층	확인 내용	자동화 여부
V1 구조	필수 파일, 폴더, 이름, 스키마	완전 자동화
V2 무결성	크기, 해시, 중복, 범위, 링크	완전 자동화
V3 실행	린트, 테스트, 빌드, 스모크 테스트	가능한 범위에서 자동화
V4 의미	요구사항, 업무 규칙, UX, 콘텐츠 정확성	모델과 도메인 검사기
V5 승인	배포, 비용, 삭제, 외부 전송	사람 승인

하위 계층이 실패하면 상위 계층을 실행하지 않는다.

5.10 실제 요청으로 전진 테스트한다

최소 시나리오:

1. 빈 저장소에서 새 작업 초기화
2. 중간 단계에서 프로세스를 종료한 뒤 재개
3. 필수 파일을 제거하고 단계 전이가 거부되는지 확인
4. 결과물을 수정한 뒤 오래된 검증이 거부되는지 확인
5. 일부 수정 요청에서 필요한 하위 단계만 재실행
6. 전체 검증을 통과한 뒤 릴리스 생성

테스트가 실패하면 프롬프트를 길게 만드는 것보다 계약이나 스크립트로 강제할 수 있는지 먼저 판단한다.

6. 신규 작업, 재개, 수정의 처리 규칙

신규 작업

상태 없음
  → 입력 범위 확인
  → init_work.py
  → 명세 작성
  → 단계별 진행

중단된 작업 재개

state.json 존재
  → 현재 stage 확인
  → 필수 아티팩트와 실제 파일 비교
  → 불완전한 현재 단계부터 계속

상태 파일만 믿지 말고 해당 단계의 필수 결과물이 실제로 존재하는지 확인한다.

부분 수정

flowchart LR
    Q["수정 요청"] --> A["최초 영향 단계 판정"]
    A --> R["해당 단계로 상태 되돌림"]
    R --> K["상위 승인 자산 보존"]
    K --> X["영향 단계와 하위 결과 재생성"]
    X --> V["검증과 패키징 재실행"]

예시:

수정 대상	복귀 단계	다시 실행할 항목
문구·설정	specified	계획부터 릴리스까지
구현 방식	planned	구현부터 릴리스까지
소스 파일	implemented	검증부터 릴리스까지
패키지 템플릿	packaged	조립과 릴리스
QA 보고서	quality_validated	승인과 릴리스

7. 안전과 운영 규칙

• 삭제, 배포, 결제, 외부 메시지 전송은 별도 승인 게이트로 둔다.
• 비밀값을 상태 파일, manifest, 로그에 저장하지 않는다.
• 생성 스크립트는 기존 작업을 기본적으로 덮어쓰지 않는다.
• 작업 디렉터리 밖의 경로를 아티팩트로 등록하지 못하게 한다.
• 검증 이후 파일이 변경되면 빌드와 릴리스를 거부한다.
• 실패를 성공으로 우회하는 플래그는 이름, 사유, 승인자, 만료 조건을 기록한다.
• 실제 운영 데이터와 생성 테스트 데이터를 분리한다.
• 기존 Git 변경이 있는 경우 하네스 작업과 무관한 파일을 보존한다.

8. 도메인별 적용 예시

웹서비스 개발

요구사항 → API/UI 설계 → 구현 → 단위·통합 테스트 → 빌드 → 배포 후보

주요 아티팩트: 요구사항, API 계약, DB 마이그레이션, 변경 파일 목록, 테스트 결과, 빌드 결과.

게임 제작

게임 규칙 → 콘텐츠/시스템 설계 → 씬·스크립트·에셋 구현 → 플레이 검증 → 빌드

주요 아티팩트: 게임 규칙, 씬 목록, 프리팹/에셋 manifest, 플레이테스트 보고서, 플랫폼 빌드.

영상 제작

브리프 → 구성안 → 대본·샷리스트 → 미디어 생성 → 렌더 검증 → 최종 인코딩

주요 아티팩트: 대본, 타임라인, 미디어 출처, 프레임/오디오 검증, 렌더 파일.

데이터 파이프라인

데이터 계약 → 변환 설계 → 파이프라인 구현 → 품질 검사 → 스냅샷·배포

주요 아티팩트: 스키마, 샘플 데이터, 변환 규칙, 품질 지표, 계보, 배포 manifest.

9. 이식용 설계 워크시트

새 프로젝트에 적용하기 전에 다음 항목을 채운다.

# Harness Design Worksheet

## 목적
- 반복할 작업:
- 최종 결과물:
- 실패 비용:

## 요청 유형
- 신규 작업:
- 이어서 하기:
- 부분 수정:
- 검증:
- 릴리스:

## 단계
1.
2.
3.
4.

## 단계별 계약
- 단계:
  - 입력:
  - 출력:
  - 자동 게이트:
  - 사람 승인:
  - 실패 시 복귀 단계:

## 영속 상태
- state 필드:
- manifest 필드:
- 보존할 연속성 정보:

## 자동화
- 초기화 스크립트:
- 등록 스크립트:
- 검증 스크립트:
- 빌드 스크립트:
- 릴리스 스크립트:

## 안전 경계
- 금지 경로:
- 외부 시스템:
- 비밀값 처리:
- 승인 필요 작업:

10. 완료 기준

다음 조건이 모두 충족되면 최소 실행 가능한 하네스로 본다.

• 자연어 요청이 적절한 스킬을 선택한다.
• 새 작업 초기화가 한 명령으로 가능하다.
• 상태 파일만으로 현재 진행 위치를 알 수 있다.
• 단계별 필수 결과물이 정의돼 있다.
• 필수 결과물 없이 단계가 넘어가지 않는다.
• 생성 결과물이 manifest에 등록된다.
• 기계 검증 결과가 파일로 남는다.
• 검증 후 변경된 아티팩트는 릴리스할 수 없다.
• 중단된 실행을 이어갈 수 있다.
• 부분 수정 시 영향받는 단계만 다시 실행할 수 있다.
• 최종 결과물이 독립된 RELEASE/ 패키지로 만들어진다.
• 알려진 제한과 승인 기록이 결과물에 포함된다.

11. 피해야 할 설계

• 하나의 거대한 프롬프트에 전체 공정을 넣는 방식
• 역할 이름만 여러 개 만들고 파일 계약을 두지 않는 방식
• 모델이 state.json을 임의로 직접 수정하게 하는 방식
• 테스트 성공 여부를 대화 문장으로만 기록하는 방식
• 생성 파일 수와 실제 논리 작업량을 혼동하는 방식
• 검증 이후 파일 변경을 감지하지 못하는 방식
• 부분 수정에도 모든 결과를 처음부터 다시 만드는 방식
• 실패를 숨기기 위해 검증 규칙을 완화하는 방식
• 중간 산출물과 사용자 원본을 같은 위치에 섞는 방식

12. 권장 도입 순서

처음부터 모든 자동화를 만들 필요는 없다. 다음 순서로 확장한다.

1. AGENTS.md, SKILL.md, _workspace/state.json으로 최소 흐름을 만든다.
2. 초기화와 단계 전이 스크립트를 추가한다.
3. manifest와 기계 검증을 추가한다.
4. 패키징과 검증 후 변경 감지를 추가한다.
5. 사람 QA와 고위험 승인 게이트를 추가한다.
6. 실제 실패 사례를 바탕으로 계약과 스크립트를 강화한다.

하네스의 완성도는 프롬프트의 길이가 아니라, 중단·오류·부분 수정·재실행 상황에서도 결과와 상태가 일치하는지로 판단한다.