Charter: AI 코딩 에이전트를 위한 결정론적 준비도 점수

AI 코딩 에이전트 (AI coding agents)는 자신이 투입되는 저장소 (repository)를 그대로 물려받습니다.

모델과는 전혀 상관없는 이유로 에이전트가 실패하는 것을 보기 전까지는, 이 말이 당연하게 들릴 것입니다.

에이전트에게 명확한 AGENTS.md, 고정된 도구 (pinned tools), 실행 가능한 테스트 (runnable tests), 안전한 기본값 (safe defaults), 그리고 이해할 수 있는 CI 경로를 제공하면, 에이전트는 대개 신중한 시니어 엔지니어처럼 행동합니다. 하지만 컨텍스트 (context)가 누락되고, MCP 서버가 @latest로 고정되어 있으며, 불분명한 컨벤션 (conventions)이 존재하고, 비밀 값 (secret)이 눈에 띄게 노출된 저장소에 에이전트를 던져 놓으면, 에이전트는 여전히 도움을 주려 할 것입니다. 아주 자신만만하게 말이죠.

그 자신감이 바로 위험한 부분입니다.

저는 똑같은 패턴을 계속 목격했습니다. 어떤 에이전트는 설정 파일에서 발견한 키 (key)를 커밋합니다. 또 다른 에이전트는 MCP 서버가 밑단에서 변경되었기 때문에 멈춰버립니다. 또 다른 에이전트는 프로젝트가 어떻게 작동해야 하는지에 대한 안내가 없어서 모듈의 절반을 다시 작성해 버립니다.

이것들은 모델의 실패가 아닙니다. 저장소의 실패입니다.

그리고 지금까지 이러한 실패는 대부분 보이지 않았습니다. 다음과 같은 질문에 대한 간단한 답이 없었습니다.

이 저장소는 AI 에이전트가 작업하기에 얼마나 안전한가?

그래서 저는 하나를 만들었습니다.

Charter가 하는 일

Charter는 AI 코딩 에이전트가 작업하기에 얼마나 준비되었는지에 따라 모든 저장소를 0점에서 100점 사이로 채점하는 오프라인 CLI (Command Line Interface)입니다.

Charter는 다음 9가지 영역을 점검합니다:

컨텍스트 (Context)
비밀 값 (Secrets)
MCP 안전성 (MCP safety)
에이전트 설정 (Agent configuration)
환경 설정 (Environment setup)
CI
테스트 (Testing)
자율성 (Autonomy)
거버넌스 (Governance)

이 영역들 아래에는 18개의 결정론적 규칙 (deterministic rules)이 있습니다. 각 규칙은 심각도 (severity), 명확한 점검 항목 (check), 그리고 구체적인 해결책 (fix)을 가지고 있습니다.

다음 명령어를 실행하세요:

charter doctor

그러면 점수, 세부 분석, 그리고 저장소를 에이전트에게 더 안전하게 만드는 데 방해가 되는 정확한 격차 (gaps)를 확인할 수 있습니다.

첫 번째 숫자는 보통 겸허해질 정도로 낮을 것입니다. 그것이 바로 이 도구의 목적이기도 합니다.

이것이 LLM이 저장소를 심사하는 방식이 아닌 이유

이 제품의 뻔한 버전은 다음과 같을 것입니다. 모델을 저장소에 연결하고 "이것이 에이전트 준비가 되었나요?"라고 묻는 것이죠.

저는 그것을 원하지 않았습니다.

재현할 수 없는 점수는 게이트(gate)가 아닙니다. 그것은 단지 느낌(vibe)일 뿐입니다.

Charter의 점수는 고정된 규칙 세트에 대한 공개된 공식입니다. 동일한 저장소라면 매번 동일한 점수가 나옵니다. 프롬프트 드리프트 (prompt drift)도 없고, API 비용도 발생하지 않습니다. 당신의 다른 모델이 충분한 컨텍스트 (context)를 가지고 있는지 여부를 모델이 스스로 결정하게 하지도 않습니다.

이것은 리뷰어 (reviewer)보다는 린터 (linter)에 더 가깝습니다.

그렇기에 가장 좋은 의미에서 지루합니다. 규칙을 읽을 수 있고, 결과를 예측할 수 있으며, 그 숫자를 신뢰하여 CI (지속적 통합)에 포함시킬 수 있기 때문입니다.

루프 (The loop)

워크플로우는 의도적으로 작게 설계되었습니다.

1. 저장소 초기화 (Initialize the repo)

charter init

이 명령은 AGENTS.md와 charter.yaml을 포함하여 에이전트가 기대하는 파일들의 스캐폴딩 (scaffolding)을 생성합니다.

2. 베이스라인 확인 (Get the baseline)

charter doctor

에이전트를 위해 준비된 적이 없는 대부분의 저장소는 40~60점 사이의 점수를 받습니다.

그것이 저장소가 나쁘다는 뜻은 아닙니다. 대개 그 저장소가 컨텍스트를 문서로 작성해야 하는 에이전트가 아니라, 이미 컨텍스트를 알고 있는 인간을 위해 구축되었음을 의미합니다.

3. 안전하게 수정 가능한 항목 수정 (Fix what is safe to fix)

charter fix

Charter는 디프 우선 (diff-first) 방식입니다. 무언가가 작성되기 전에 무엇을 변경하고 싶은지 먼저 보여줍니다.

또한 엄격한 경계가 있습니다. 비밀 정보 (secrets)나 파괴적인 명령은 절대 자동으로 건드리지 않습니다. Charter는 이를 지적할 수는 있지만, 직접 손을 대지는 않습니다.

CI에도 포함되어야 합니다

로컬 점수도 유용하지만, CI 게이트 (gate)는 더 좋습니다.

Charter는 SARIF 2.1.0을 출력하므로, 발견된 사항들이 GitHub Code Scanning에 나타날 수 있습니다. 또한 점수 임계값 (threshold)을 설정할 수 있는 공식 GitHub Action도 있습니다:

- uses: use-charter/charter-action@v1
  with:
    threshold: 80

이를 통해 "이 저장소는 에이전트 준비가 된 것 같다"라는 모호한 느낌을 훨씬 더 이성적으로 판단할 수 있는 상태로 바꿀 수 있습니다:

머지 (merge)하기 전에 이 저장소는 반드시 80점 이상을 유지해야 한다.

점수는 일회성 정리 프로젝트가 아니라, 시간이 지남에 따라 점진적으로 높아질 수 있습니다.

계약 (The contract)

Charter는 몇 가지 확고한 약속을 합니다:

네트워크 호출 없음 (No network calls)
핵심 점수 산출 경로 내 LLM 미사용 (No LLM in the core scoring path)
파일 삭제 없음 (No file deletion)
암묵적 변이 없음 (No silent mutation)
모든 발견 사항은 규칙으로 매핑됨 (Every finding maps back to a rule)
모든 규칙에는 수정 방법이 포함됨 (Every rule includes a fix)
동일한 바이너리가 로컬과 CI에서 작동함 (The same binary works locally and in CI)
릴리스는 서명되었고, SLSA 방식으로 빌드되며, SBOM과 함께 배포됨 (Releases are signed, SLSA-built, and shipped with SBOMs)

Apache-2.0 라이선스이며 영구적으로 무료입니다.

사용해 보기

Homebrew로 설치하세요:

brew install use-charter/tap/charter
charter doctor

또는 Go로 설치하세요:

go install go.use-charter.dev/charter/cmd/charter@latest

릴리스(releases) 페이지에서 서명된 바이너리를 직접 내려받을 수도 있습니다.

문서와 전체 규칙 목록은 여기에서 확인할 수 있습니다:

https://use-charter.dev/

소스 코드는 GitHub에 있으며, 유용하다고 생각되시면 별(star)을 눌러주세요.

어떤 규칙이 누락되었다고 생각하시는지 진심으로 듣고 싶습니다.

처음 나오는 점수는 보통 겸허해질 정도로 낮을 것입니다. 그 점수를 고쳐나가는 것이 바로 이 도구의 목적입니다.