SAGE - System for Agentic Governance & Engineering
Claude Code나 Codex 같은 AI 코딩 에이전트가 계획 없이 위험한 코드를 고치거나, 리뷰 없이 "완료"라고 보고하지 않도록 자동으로 확인하고 막는 도구입니다.
왜 필요한가
AI 에이전트에게 "먼저 계획을 세우고, 위험한 파일은 조심히 다루고, 꼭 리뷰를 받아라"라고 매번 말해줘도 그 지시는 결국 잊히거나 생략되기 쉽습니다. SAGE는 이런 규칙을 사람이 반복해서 말하는 대신, 자동으로 확인하는 장치(hook)로 만듭니다.
- 계획 없이 위험한 파일을 고치려 하면 → 먼저 계획 문서를 쓰라고 막습니다.
- 리뷰 없이 "완료됐다"고 보고하면 → 승인된 리뷰가 있는지 확인하고 없으면 막습니다.
- AI가 자동 생성된 설정 파일을 직접 고치면 → 그 원본 정의를 고치도록 안내합니다(직접 고치면 다음 생성 때 덮어써지므로).
- 한 AI가 자기가 짠 코드를 자기가 검토하면 → 반대 모델(Claude ↔ Codex)에게 독립적으로 검토를 맡길 수 있습니다.
이 확인들은 AI의 "판단"이 아니라 코드가 "결정론적으로" 검사합니다 — 같은 상황이면 항상 같은 결과가 나오고, 사람이 매번 다시 설명할 필요가 없습니다.
빠른 시작
요구사항은 Python 3.10+와 Git입니다.
먼저 SAGE 자체를 설치합니다.
pipx install "sage-harness[schema]"
cd your-project
그다음 쓰고 있는 AI 도구에 맞는 쪽 하나만 따라 하세요. 두 쪽 다 실행할 필요는 없습니다.
Codex를 쓰는 경우
sage install --host codex --skill-scope project-local
설치가 끝나면 Codex 안에서 $sage-init을 실행해 이 프로젝트의 설정(profile)을 대화로 채웁니다.
그다음 터미널로 돌아와 마무리합니다.
sage generate --kind hook --write --target codex
sage validate --kind all
Claude Code를 쓰는 경우
sage install --host claude
설치가 끝나면 Claude Code 안에서 /sage-init을 실행해 이 프로젝트의 설정(profile)을 대화로
채웁니다. 그다음 터미널로 돌아와 마무리합니다.
sage generate --kind hook --write --target claude
sage validate --kind all
공유 profile이 이미 있는 프로젝트에 합류했다면 sage-init 대신 sage-init-local만 실행합니다.
더 자세한 단계는 퀵스타트, 설치 중 오류는 문제 해결을
참조하세요.
SAGE 1.0의 주요 기능
| 하고 싶은 일 | 명령 또는 기능 |
|---|---|
| 지금 프로젝트에서 SAGE를 쓸 수 있는지 확인 | sage status |
| 특정 경로가 왜 차단되는지 확인 | sage explain --path PATH |
| 리뷰·우회·유예 감사 기록 조회 | sage audit show |
| 정의와 생성 자산의 무결성 검사 | sage validate --kind all |
| 다른 SAGE 버전으로 안전하게 이동 | sage upgrade --check → sage upgrade --apply |
| 설치한 프로젝트·전역 자산 제거 | sage uninstall --check → sage uninstall --yes |
| 계획·구현·독립 리뷰·완료 증거 결속 | 표준 PDCA, Fast Cycle, Done Criteria |
status, explain, audit show, upgrade --check, uninstall --check는 읽기 전용 진단입니다.
자동화용 --json, 전체 옵션과 종료 코드는 CLI 레퍼런스를 참조하세요.
지원 환경
SAGE의 일반 CLI와 설치 hook은 Python 3.10+에서 동작하며 Windows에서도 bash가 필요 없습니다. 다만
표준 L2/L3 전달 흐름의 scripts/verify-changes.sh와 사용자 정의 .sh 테스트에는 Git Bash가 필요합니다.
sage uninstall의 자동 제거 지원 범위는 더 좁습니다. 파일을 지우는 기능이므로 검증되지 않은
환경에서는 추측해서 실행하지 않고 첫 변경 전에 멈춥니다.
| 환경 | 일반 CLI·hook | sage uninstall |
|---|---|---|
| Linux | 지원 | 자동 제거 지원 |
| macOS | 지원 | 자동 제거 지원 |
| Windows 11 데스크톱 workstation, x64, 64-bit Python, 로컬 NTFS | 지원 | 자동 제거 지원 |
| Windows 10 데스크톱 | 지원 | 자동 제거 후순위; 현재는 검증된 계획과 수동 정리 목록 제공 |
| Windows Server·도메인 컨트롤러 | 정식 지원 범위 밖 (직접 검증하지 않음) | 자동 제거 미지원; 계획 기반 수동 목록 제공 |
| 32-bit Python, native ARM64 Python, 비 NTFS·네트워크·UNC 경로 | 환경별 제한 | 자동 제거하지 않음; --check로 계획 확인 가능 |
NTFS는 일반적인 Windows 로컬 디스크의 기본 파일 시스템입니다. 동작할 수 있다는 것과 정식으로 지원한다는 것은 다릅니다 — 범위 밖 환경에서 일반 CLI가 도는 경우가 있어도 그 동작을 약속하지 않고, 직접 검증하지도 않습니다. Windows 11 데스크톱의 자동 제거는 그 SKU에서 실제로 실행해 검증했습니다 — Windows Server 결과로 갈음하지 않았습니다. 두 종류의 거부 화면과 자세한 판정은 CLI 레퍼런스와 문제 해결에 있습니다.
Windows 설치 예시입니다. sage-hook.exe가 hook을 실행하므로 Git Bash나 WSL은 필요 없습니다.
py -m pip install --user pipx
py -m pipx ensurepath
pipx install "sage-harness[schema]"
sage doctor
Windows에서 .sh 테스트를 실행할 때는 SAGE_BASH로 Git Bash 경로를 명시합니다.
1.0으로 업그레이드
0.9.x에서 1.0으로 이동할 때는 패키지를 먼저 올린 뒤 프로젝트 자산을 점검·적용합니다.
pipx upgrade sage-harness
sage upgrade --check
sage upgrade --apply
sage status
--check는 계획만 보여 줍니다. --apply는 transaction이라 실패하면 되돌리고, 자동 downgrade는 없습니다.
안전하게 제거
먼저 실제 프로젝트별 계획을 확인한 뒤 제거합니다. 패키지 자체는 별도로 지웁니다.
sage uninstall --check
sage uninstall --yes
pipx uninstall sage-harness
자동 제거가 지원되지 않는 환경에서도 두 명령은 실제 경로를 STRIP(공유 파일에서 SAGE 부분만
제거) · DELETE · PRESERVE · BLOCK으로 나눠 보여 줍니다. 대상은 host·scope·프로젝트 위치·
CODEX_HOME에 따라 달라지므로 고정 목록을 여기 싣지 않습니다. 출력된 목록을 따르되 PRESERVE와
BLOCK은 지우지 마세요 — 손 대는 법은 문제 해결에 있습니다.
어떻게 동작하는가
SAGE는 두 종류의 파일을 나눠서 관리합니다 — 사람이 고치는 정의 파일과, 그로부터 자동으로 만들어져 AI가 실제로 읽는 실행 파일입니다.
정의 파일 (사람이 고침) sage generate 실행 파일 (AI가 읽음)
hook / agent / skill spec <------------------> .claude / .codex
| |
+---- 확인 --- sage validate ---------------------+
+---- 직접 고치려 하면 ----> 정의 파일을 고치라고 안내
정의 파일을 고치고 sage generate를 실행하면 실제 AI가 읽는 실행 파일이 자동으로 갱신됩니다. 두 파일이
어긋나면(직접 고쳤거나 갱신을 깜빡했으면) sage validate가 잡아냅니다. AI가 실행 파일을 직접 고치려
하면 SAGE가 막고, 대신 정의 파일을 고치도록 안내합니다.
판단이 필요한 코드 작성과 리뷰는 AI가 담당하고, 무결성·단계·승인 경계는 SAGE가 코드로 검사합니다. 더 자세한 신뢰 경계와 실패 정책은 Architecture에 있습니다.
개발 절차
- PDCA — 계획 → 구현 → 독립 리뷰 → 완료보고를 결속합니다.
- 완료 기준(Done Criteria) — 요구별 증거를 추적하고, 기준이 바뀌면 영향받은 단계를 다시 검증합니다.
- profile — 팀 공유 정책과 개인 환경 설정을 분리합니다.
- Fast Cycle — 명시적으로 켠 경우 문서 수를 줄이되 전환 과정을 감사 기록에 남깁니다.
- 조기 완료 승인 — 사용자가 남은 위험을 명시적으로 인수했을 때만 일반 승인과 구분해 기록합니다.
문서
| 목적 | 문서 |
|---|---|
| 처음 설치하고 실행 | 퀵스타트 |
| 명령과 옵션 확인 | 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이 적용됩니다.
1 maintainer
Metadata
1 maintainer
Release files for sage-harness 1.0.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| sage_harness-1.0.0.tar.gz | 1.6 MB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| sage_harness-1.0.0-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 3.4 MB
Release files / sage_harness-1.0.0.tar.gz
| Download URL | sage_harness-1.0.0.tar.gz |
|---|---|
| Size | 1.6 MB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
125e9fbf2dc2a1e671408888731f91873374bd29f4855f9e33b7ac2054592e92
|
|
BLAKE2b-256 checksum How to use checksums |
7cd6be9d78680585faa351d6a68db670c816f268e569abbec643cef46c09b652
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 9, 2026.
Transparency logRelease files / sage_harness-1.0.0-py3-none-any.whl
| Download URL | sage_harness-1.0.0-py3-none-any.whl |
|---|---|
| Size | 1.7 MB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
0c8bc2d2032f02692ded8d271a8f36e089fecc0c5c07b8c7be1e793f3124e8ca
|
|
BLAKE2b-256 checksum How to use checksums |
f7b6fb6b74365dff90c1a74ce3acb5bc420bdf5bd7da7e16577119a496b334d6
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 9, 2026.
Transparency log
