sage-harness 0.9.73

Governance harness for AI coding agents — spec-SSOT closed loop for Claude Code and Codex

SAGE - System for Agentic Governance & Engineering

English

Claude Code와 Codex를 위한 결정론적 거버넌스 하네스입니다. hook/MCP spec과 agent/skill host render를 정본 입력으로 관리하고, drift를 검증하며, hook이 정책 위반을 실행 전에 차단합니다.

왜 SAGE인가

AI 코딩 에이전트는 빠르지만 plan 없이 고위험 파일을 수정하거나, PDCA 단계를 건너뛰거나, 생성물을 직접 고칠 수 있습니다. SAGE는 사람이 같은 지시를 반복하는 대신 다음 폐루프를 제공합니다.

spec 작성 -> 런타임 자산 생성 -> manifest 검증 -> hook 차단 -> 리뷰와 회고

• spec SSOT: hook, agent, skill, MCP 정의를 추적 가능한 문서로 관리합니다.
• 실행 게이트: 위험도, PDCA phase, 리뷰 승인, 생성물 직접수정을 결정론적으로 검사합니다.
• 듀얼 호스트: 같은 정책 core를 Claude Code와 Codex의 I/O 규약에 맞춰 실행합니다.
• 교차 모델 리뷰: 현재 실행 중인 host가 아닌 peer runtime에 독립 리뷰를 맡길 수 있습니다.
• 감사 가능성: manifest, phase 문서, review-loop, retro 기록을 저장합니다.

빠른 시작

요구사항은 Python 3.10+와 Git입니다. 설치 hook은 Windows에서도 bash 없이 동작합니다.

pipx install "sage-harness[schema]"

cd your-project
sage install --host codex --skill-scope project-local
# Codex에서 최초 설정: $sage-init
sage generate --kind hook --write --target codex
sage validate --kind all

# Claude Code를 쓰는 경우:
# sage install --host claude
# /sage-init
# sage generate --kind hook --write --target claude

공유 profile이 이미 있는 프로젝트에 합류했다면 sage-init-local만 실행합니다. 단계별 설명은 한국어 퀵스타트, 설치 문제는 문제 해결을 참조하세요.

Windows

sage-hook.exe가 7개 설치 hook을 Python으로 실행하므로 hook 실행에는 Git Bash나 WSL이 필요하지 않습니다.

py -m pip install --user pipx
py -m pipx ensurepath
pipx install "sage-harness[schema]"
sage doctor

표준 L2/L3 전달 흐름의 scripts/verify-changes.sh와 사용자 정의 .sh 회귀 테스트에는 Git Bash가 필요합니다. Windows에서 후자를 실행할 때는 SAGE_BASH로 인터프리터를 명시합니다.

동작 원리

hook / MCP specs                  sage generate       host assets
agent / skill host renders    <------------------>   .claude / .codex
          |                                               |
          +---- manifest hash <--- sage validate ---------+
          +---- blocked edit ----> sage absorb proposal

판단이 필요한 코드 작성과 리뷰는 AI가 담당하고, 무결성·단계·승인 경계는 SAGE가 코드로 검사합니다. 신뢰 경계와 fail-open/fail-closed 정책은 Architecture에 있습니다.

핵심 흐름

자산 관리

종류	작성 흐름	대표 산출물
hook	spec-first: docs/sage_harness/hooks/{id}.md	host hook 등록 + Python runtime
agent	render-first: 두 host render를 작성한 뒤 spec/claims 추출	.claude/agents, .codex/agents
skill	render-first: 두 host render를 작성한 뒤 spec/claims 추출	.claude/skills, .codex/skills
MCP	spec-first: docs/sage_harness/mcps/{id}.md	.mcp.json, .codex/config.toml

생성된 파일을 직접 수정하면 write guard가 차단합니다. hook/MCP는 spec을 수정한 뒤 generate합니다. agent/skill은 두 host render를 작성한 뒤 generate로 spec과 claims를 역추출합니다. 이미 생긴 차단 diff는 sage absorb로 spec patch 후보로 변환할 수 있습니다.

PDCA와 리뷰

sage-cycle은 Phase 00-06을 구동합니다. sage-plan은 기획 00-02, sage-team은 구현 03-06, sage-review는 Phase 05 리뷰와 적대적 반복을 담당합니다. sage review-loop는 라운드를 기록하고, sage retro는 완료 후 놓친 패턴을 분석합니다.

Profile

sage/project-profile.yaml은 팀이 공유하는 정책이고, Git에서 제외되는 sage/project-profile.local.yaml은 현재 머신의 host/model/vault capability입니다. 로컬 profile은 공유 risk나 review 정책을 완화할 수 없습니다.

문서

목적	문서
처음 설치하고 실행	퀵스타트
명령과 옵션 확인	CLI 레퍼런스
profile 설정	Profile 레퍼런스
오류 해결	문제 해결
설계와 신뢰 경계	Architecture
생성 위치와 소유권	Artifacts
전체 문서 지도	문서 인덱스

적합한 사용자

SAGE는 Claude Code 또는 Codex로 실무 저장소를 변경하면서, prompt 권고가 아니라 검증 가능한 정책과 독립 리뷰가 필요한 팀을 위한 도구입니다. 단순 prompt 모음이나 코드 생성 스니펫이 필요한 경우에는 과한 선택일 수 있습니다.

라이선스

Apache License 2.0입니다. 상업적 이용, 수정, 재배포가 가능하며 배포물에는 LICENSE와 NOTICE를 포함해야 합니다. v0.9.71 이전 배포분은 CC BY-NC-SA 4.0이 적용됩니다.