SAGE - System for Agentic Governance & Engineering

English

Claude Code나 Codex 같은 AI 코딩 에이전트가 계획 없이 위험한 코드를 고치거나, 리뷰 없이 "완료"라고 보고하지 않도록 자동으로 확인하고 막는 도구입니다.

왜 필요한가

AI 에이전트에게 "계획부터 세우고, 위험한 파일은 조심히 다루고, 꼭 리뷰를 받아라"라고 매번 말해도 그 지시는 잊히거나 생략됩니다. SAGE는 그 규칙을 자동으로 확인하는 장치(hook)로 만듭니다.

계획 없이 위험한 파일을 고치려 하면 → 먼저 계획 문서를 쓰라고 막습니다.
리뷰 없이 "완료됐다"고 보고하면 → 승인된 리뷰가 있는지 확인하고 없으면 막습니다.
AI가 자동 생성된 설정 파일을 직접 고치면 → 그 원본 정의를 고치도록 안내합니다(직접 고치면 다음 생성 때 덮어써지므로).
한 AI가 자기가 짠 코드를 자기가 검토하면 → 반대 모델(Claude ↔ Codex)에게 독립적으로 검토를 맡길 수 있습니다.
cross-review 및 loop를 사용하는 만큼 토큰 사용량이 높을 수 있습니다.

이 확인들은 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만 실행합니다. 이미 CLAUDE.md·AGENTS.md가 있으면 설치가 멈춥니다(무변경) — 절차는 퀵스타트와 문제 해결.

주요 기능

하고 싶은 일	명령 또는 기능
지금 프로젝트에서 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가 필요 없습니다. 다만 sage_harness/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 경로를 명시합니다.

업그레이드

패키지를 먼저 올린 뒤 프로젝트 자산을 점검·적용합니다.

pipx upgrade sage-harness
sage upgrade --check
sage upgrade --apply
sage status

--check는 계획만 보여 줍니다. --apply는 transaction이라 실패하면 되돌립니다. 1.0에서 올라오면 설치 위치가 sage_harness/ 한 곳으로 모입니다 — 옮기지 않고 새로 만들어 검증한 뒤 옛 것을 지우고, 직접 넣은 파일과 직접 쓴 hook 앞에서는 멈춥니다(troubleshooting).

안전하게 제거

먼저 실제 프로젝트별 계획을 확인한 뒤 제거합니다. 패키지 자체는 별도로 지웁니다.

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이 적용됩니다.

Metadata

Release files for sage-harness 1.3.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for sage-harness 1.3.0
File	Size	Uploaded
sage_harness-1.3.0.tar.gz	1.8 MB	Oct 7, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for sage-harness 1.3.0
File	Interpreter	ABI	Platform	Reset
sage_harness-1.3.0-py3-none-any.whl 1.9 MB Oct 7, 2026	Python 3	none	any	Details

Total release size: 3.7 MB

Release files / sage_harness-1.3.0.tar.gz

Download URL	sage_harness-1.3.0.tar.gz
Size	1.8 MB
Tags	Source
SHA-256 checksum How to use checksums	`e18604c7ab4c894b1bde280fe6aa87879df1a10331e9502309cfb61314a9d775`
BLAKE2b-256 checksum How to use checksums	`d72680c16e06a975b207dfa76bb4020b883e1fafbf66d77188909897195115b6`
Upload date	Oct 7, 2026
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.

Identity

Publishing platform: GitHub Actions
Publishing repository: github.com/SeJonJ/SAGE
Publishing commit: github.com/SeJonJ/SAGE/tree/ef6c59a1c546dd823b3433da7193e72d07be202f

Workflow

Publishing configuration: github.com/SeJonJ/SAGE/blob/ef6c59a1c546dd823b3433da7193e72d07be202f/.github/workflows/publish.yml
Publishing logs: github.com/SeJonJ/SAGE/actions/runs/37618763653/attempts/1

Artifact

Subject: sage_harness-1.3.0.tar.gz
SHA-256 checksum: e18604c7ab4c894b1bde280fe6aa87879df1a10331e9502309cfb61314a9d775 Verifying attestations

Release files / sage_harness-1.3.0-py3-none-any.whl

Download URL	sage_harness-1.3.0-py3-none-any.whl
Size	1.9 MB
Tags	Python 3
SHA-256 checksum How to use checksums	`56d755a28db7e997563f61b21bc514f69b16ae1a2b052b0acf177e202c589ce7`
BLAKE2b-256 checksum How to use checksums	`0f33b070dc9792050fb9983f0123828518df40a435bc6c2b4bdcb3f67d412723`
Upload date	Oct 7, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/7.0.0 CPython/3.13.14`

Provenance

Identity

Publishing platform: GitHub Actions
Publishing repository: github.com/SeJonJ/SAGE
Publishing commit: github.com/SeJonJ/SAGE/tree/ef6c59a1c546dd823b3433da7193e72d07be202f

Workflow

Publishing configuration: github.com/SeJonJ/SAGE/blob/ef6c59a1c546dd823b3433da7193e72d07be202f/.github/workflows/publish.yml
Publishing logs: github.com/SeJonJ/SAGE/actions/runs/37618763653/attempts/1

Artifact

Subject: sage_harness-1.3.0-py3-none-any.whl
SHA-256 checksum: 56d755a28db7e997563f61b21bc514f69b16ae1a2b052b0acf177e202c589ce7 Verifying attestations