MoAI-ADK는 하네스 엔지니어링 (Harness Engineering) 패러다임을 구현합니다. 개발자가 직접 코드를 작성하는 대신, AI 에이전트가 최적의 코드를 생산할 수 있는 환경 (하네스) 을 설계하는 접근 방식입니다. 왜냐하면 에이전트의 출력 품질이 모델 자체의 능력만큼이나 그 에이전트를 감싼 환경에 달려 있기 때문입니다. 그래서 harness 설계가 곧 코드 품질 설계가 되고, 여기서 SPEC 3-단계 워크플로우와 TRUST 5 게이트가 매 단계마다 에이전트의 출력을 검사합니다.

“Human steers, agents execute.” — 엔지니어의 역할은 코드 작성에서 하네스 설계로 전환됩니다: SPEC, 품질 게이트, 피드백 루프.

기존 바이브코딩은 AI에게 자유롭게 코드를 생성하게 한 뒤 결과를 사람이 하나하나 검토합니다. 하네스 엔지니어링은 그 반대입니다 — 규격 (SPEC), 자동 검증, 지속적 피드백 루프로 AI 에이전트를 이끌어 품질이 흔들리지 않는 코드를 만들어 냅니다.

그럼 하네스란 무엇일까요? 기본 모델을 감싸고 실행을 지휘하는 시스템 전체를 말합니다. 모델이 어떻게 생각하고 계획할지, 도구를 어떻게 호출할지, 컨텍스트를 어떻게 인지하고 관리할지, 산출물을 어디에 저장할지, 결과를 어떻게 평가할지를 결정하는 계층입니다. MoAI-ADK는 Claude Code 위에 얹히는 바로 이 하네스입니다.

하네스 엔지니어링은 v3.0의 세 가지 핵심이 만나는 지점입니다.

특히 두 번째 핵심이 지금의 발전을 이끕니다. AI가 스스로를 재귀적으로 개선하는 (RSI) 현실적인 단기 경로는 모델 가중치를 직접 손보는 쪽이 아니라 모델을 감싼 하네스를 개선하는 쪽입니다. MoAI-ADK는 정확히 이 길을 따릅니다 — 모델이 아니라 하네스 (스킬·에이전트 지침) 를 재귀적으로 개선합니다.

graph TD
    subgraph Harness["하네스 엔지니어링"]
        direction TB
        SF["Scaffolding First
빈 파일 스텁 생성"] --> FC["Failing Checklist
수락 기준 태스크 등록"]
        FC --> SV["Self-Verify Loop
코드→테스트→수정→통과"]
        SV --> GC["Garbage Collection
데드 코드 제거"]
        GC --> CM["Context Map
아키텍처 문서 유지"]
        CM --> SP["Session Persistence
세션 간 진행 추적"]
        SP --> LA["Language-Agnostic
16개 언어 자동 감지"]
        LA --> SF
    end

    style Harness fill:#f0f7ff,stroke:#1565C0

각 컴포넌트는 MoAI의 특정 명령어에 매핑됩니다:

/moai run이 시작되면, 에이전트는 코드를 작성하기 전에 먼저 필요한 파일 구조를 생성합니다:

src/
├── auth/
│   ├── handler.go      ← 빈 스텁
│   ├── handler_test.go  ← 빈 테스트
│   ├── service.go       ← 빈 스텁
│   └── service_test.go  ← 빈 테스트
└── middleware/
    └── jwt.go           ← 빈 스텁

이렇게 해 두면 에이전트가 파일을 아무 데나 만드는 일을 막고 프로젝트 구조를 일관되게 유지할 수 있습니다.

SPEC의 수락 기준이 자동으로 태스크 목록에 등록됩니다:

- [ ] JWT 토큰 생성 엔드포인트
- [ ] 토큰 검증 미들웨어
- [ ] 리프레시 토큰 로직
- [ ] 만료된 토큰 처리
- [ ] 85%+ 테스트 커버리지

각 항목이 구현되고 테스트를 통과하면 체크됩니다. 모든 항목이 체크되어야 작업이 완료됩니다.

에이전트가 자율적으로 실행하는 핵심 사이클:

graph TD
    A["코드 작성"] --> B["테스트 실행"]
    B --> C{"통과?"}
    C -->|"실패"| D["에러 분석"]
    D --> A
    C -->|"통과"| E["다음 항목"]

이 루프는 /moai loop에서 기본 최대 10회까지 반복되며, 수렴 감지 (같은 에러 반복 시 대안 전략 적용) 를 포함합니다. 완료 조건을 직접 선언하고 싶다면 goal 엔진 (/moai goal "<조건>") 을 사용합니다 — 조건이 충족되거나 턴 한도에 닿을 때까지 세션이 스스로 일합니다.

/moai codemaps가 만들어 두는 아키텍처 문서는 코드베이스의 전체 구조를 에이전트에게 그대로 넘겨줍니다. 그 덕분에 에이전트는 다음을 할 수 있습니다:

• 기존 코드와 충돌하지 않는 구현 방법을 선택
• 적절한 패턴과 규칙을 따름
• 의존성 관계를 이해하고 영향 범위를 파악

Claude Code 세션이 중단되더라도 progress.md가 완료된 단계를 기록합니다:

## Progress
- [x] Phase 1: 분석 완료
- [x] Phase 2: 핸들러 구현
- [ ] Phase 3: 테스트 작성 ← 여기서 재개
- [ ] Phase 4: 리팩토링

/moai run --resume SPEC-XXX로 중단된 지점부터 자동으로 재개됩니다.

하네스는 고정된 환경이 아닙니다. 루프가 돌수록 관찰이 쌓이고, 하네스가 그 관찰로 학습해 스스로 지침을 개선합니다.

루프 실행 → 관찰 축적 → 패턴 학습 → 지침 진화 (승인 게이트)

자동 진화가 인간 감시 없이 닫힌 루프를 도는 일은 없습니다. 평가자와 권한 통제는 진화 루프의 밖에 둡니다:

• 5-계층 안전 파이프라인 — 스냅샷과 롤백 (moai harness rollback) 으로 언제든 복원할 수 있습니다
• 사용자 승인 게이트 — Tier-4 자동 업데이트는 반드시 사용자 승인을 거칩니다
• Constitution 시스템 — 불변 규칙 (FROZEN) 은 진화 대상에서 제외됩니다 (Constitution 시스템 참조)

moai harness status      # 학습 상태 확인 (관찰 수, 패턴, 제안)
moai harness apply       # 제안 적용 (사용자 승인 게이트 통과 필요)
moai harness rollback    # 직전 적용 롤백
moai harness disable     # 학습 비활성화

지침을 고치는 일도 하나의 실험입니다. 규칙·에이전트·훅 같은 하네스 구성요소를 수정할 때는 결정 관측성이 적용됩니다. 편집할 때마다 반증할 수 있는 예측 (어떤 실패 클래스가 사라지는가) 을 적어 두고, 채택하기 전에 두 가지 검사를 통과해야 합니다 — held-in (원래 잡으려던 실패를 실제로 잡는가) 과 held-out (기존 가드·테스트가 여전히 통과하는가). 기각된 편집도 기록으로 남기 때문에, 이미 실패한 시도를 다시 되풀이하지 않습니다.

직접 커스텀 스킬이나 에이전트를 만들 때, moai update가 어떤 자산을 덮어쓰고 (overwrite) 어떤 자산을 보존 (preserve) 하는지 알아야 합니다. MoAI-ADK는 네임스페이스를 “범용 배포 (template-managed)” 와 “사용자 생성 (user-owned)” 으로 명확히 분리합니다.

moai-* prefix 스킬과 moai-harness-*는 MoAI-ADK 패키지가 제공하는 범용 자산입니다. 모든 사용자 프로젝트에 배포되며, moai update를 실행하면 최신 template으로 덮어쓰기됩니다. 그래서 이 자산을 직접 수정하면 다음 업데이트 때 고친 내용이 사라집니다.

hns-* prefix 스킬 (Harness v4 Builder가 생성하는 정식 네임스페이스) 과 .claude/agents/harness/ 디렉터리는 사용자 프로젝트가 소유합니다. 이전 세대 prefix인 harness-* / my-harness-* 도 동일하게 인식됩니다. moai update는 이들을 절대 삭제하거나 수정하지 않으며, 업데이트 전에 백업한 뒤 그대로 보존합니다.

직접 만든 도메인 특화 스킬이나 에이전트가 moai update 뒤에도 살아남게 하려면 반드시 hns-* prefix를 사용하세요 (에이전트는 .claude/agents/harness/ 에 배치). moai-* 또는 moai-harness-* prefix를 쓰면 template-managed로 분류되어 다음 업데이트 때 덮어써집니다. /moai harness "자연어 요청" 으로 하네스를 생성하면 Builder가 이 규칙에 맞는 이름을 자동으로 배정합니다.

• SPEC 기반 개발 — 하네스의 입력이 되는 SPEC 문서 작성법
• TRUST 5 품질 — 하네스가 검증하는 5가지 품질 기준
• Constitution 시스템 — 하네스 진화를 통제하는 불변 규칙