Abide의 기능
Abide는 일반적인 린터로는 안정적으로 평가할 수 없는 프로젝트별 지침을 적용합니다. 이러한 지침은 AGENTS.md 또는 CLAUDE.md 같은 파일에 있을 수 있으며, 수동 검증 대신 Yup을 사용하라, 호출자가 하나뿐인 헬퍼를 만들지 마라, 사용자에게 원시 오류를 노출하지 마라와 같은 규칙을 포함합니다.
각 수정 또는 완료된 턴이 끝나면 Abide는 관련 규칙과 코드 diff를 TypeSafe의 Jev 의사 결정 모델로 보냅니다. Jev는 자유 형식의 문장 대신 확률을 반환합니다. 확률이 위반을 나타내면 Abide는 코딩 에이전트에 위반된 규칙을 알려 주고 같은 턴에 코드를 수정하도록 요청합니다.
Jev는 에이전트의 대화가 아니라 규칙과 diff를 확인합니다. 따라서 Abide는 긴 코딩 세션 전체에서 동일한 검사를 일관되게 적용할 수 있습니다. 저장소에서 공개한 replay 벤치마크에 따르면 Jev에서 검사를 수행하는 데 약 300밀리초가 걸리며, Node 시작 시간을 포함한 전체 훅 실행에는 약 1초가 걸립니다.
주요 기능
- 자동 수정 검사: 각 코드 수정 직후 규칙을 실행할 수 있습니다.
- 턴 단위 검사: 전체 작업 diff가 필요한 규칙은 턴이 끝날 때 한 번 실행할 수 있습니다.
- 에이전트 통합: Abide는 Claude Code, Codex, OpenCode를 지원합니다.
- 저장소 소유 루브릭: 컴파일된 규칙은 읽기 쉽고 커밋하기 편한
.abide/rubric.json파일에 저장됩니다. - 범위 지정 규칙: 규칙에서 glob 범위를 사용하면 API 경로, 스타일시트 또는 다른 파일 그룹에 서로 다른 질문을 적용할 수 있습니다.
- 기존 코드 감사: Abide는 파일이 방금 작성된 것처럼 판단할 수 있습니다.
- 캘리브레이션 및 조정: 최근 Git 기록을 기준으로 규칙을 테스트하고, 효과가 없는 규칙을 비활성화하며, 전혀 실행되지 않는 규칙을 다시 작성하도록 지원할 수 있습니다.
- Fail-open 훅: 인증 정보 누락, 네트워크 오류 또는 훅 오류가 코딩 세션을 차단하지 않습니다.
- 내장 정책 없음: Abide는 미리 정의된 규칙 세트를 강제하는 대신 사용자가 직접 작성한 지침 파일에서 도출된 규칙을 적용합니다.
사전 요구 사항
코딩 에이전트용 지침이 있는 저장소와 지원되는 에이전트 중 하나 이상이 필요합니다. 지원되는 에이전트는 Claude Code, Codex, OpenCode입니다. 또한 typesafe.ai에서 발급한 TypeSafe API 키가 필요합니다. 또는 AI_GATEWAY_API_KEY 환경 변수를 통해 기존 Vercel AI Gateway 키를 사용할 수 있습니다.
Abide 설치 및 구성
1단계: API 키 저장
로그인 명령을 실행하고 메시지가 표시되면 TypeSafe 키를 붙여 넣습니다.
npx @coldtea/abide loginAbide는 소유자만 접근할 수 있도록 키를 ~/.abide/.env에 저장합니다. 대신 저장소 루트의 .env.local 또는 .env에 인증 정보를 저장할 수 있습니다. 인증 정보 조회 순서는 먼저 환경 변수를 확인하고, 그다음 저장소 파일, 마지막으로 ~/.abide/.env를 확인합니다.
Vercel AI Gateway를 사용하는 경우 TypeSafe 키 대신 AI_GATEWAY_API_KEY를 설정합니다. 인증 정보는 명령줄 플래그로 전달할 수 없으며 로그에도 기록되지 않습니다.
2단계: 에이전트 훅 설치
저장소에서 Abide를 초기화합니다.
npx @coldtea/abide init에이전트 이름을 지정하지 않으면 init이 검색된 모든 지원 에이전트에 설치합니다. 특정 통합을 명시적으로 지정할 수도 있습니다.
npx @coldtea/abide init claude
npx @coldtea/abide init codex
npx @coldtea/abide init opencode- Claude Code: 통합이
~/.claude/settings.json에 추가됩니다. - Codex: 통합이
~/.codex/hooks.json에 추가됩니다. - OpenCode: 플러그인이
~/.config/opencode/plugins/abide.js에 설치됩니다.
체크아웃을 통해 팀원도 받을 수 있는 저장소 수준의 설치를 원하면 --project를 추가합니다.
npx @coldtea/abide init claude --projectCodex에는 추가 승인 단계가 필요합니다. Codex를 시작하고
/hooks를 입력한 다음 Abide 훅 항목 4개를 승인합니다. Codex는 새 훅마다 한 번씩 이 승인을 요청합니다.
3단계: 저장소 규칙 컴파일
코딩 에이전트를 평소처럼 시작합니다. 첫 세션이 시작될 때 Abide는 지침 파일이 변경되었는지 확인합니다. 그런 다음 에이전트는 적용 가능한 지침을 .abide/rubric.json으로 컴파일하고 확인한 내용을 보고합니다.
새 세션을 시작하기 전에 미리 컴파일할 수도 있습니다.
abide compile저장소에서 적용 가능한 루브릭을 팀이 확인하고 검토할 수 있도록 하려면 .abide/rubric.json을 커밋합니다. 모든 판정에는 이 파일의 규칙이 식별되며, 해당 규칙이 도출된 원본 지침이 인용됩니다.
기본 사용법
Abide가 에이전트 수정을 자동으로 검사하도록 하기
초기화가 완료되면 평소처럼 claude, codex 또는 opencode를 시작합니다. 별도의 백그라운드 서비스는 필요하지 않습니다. API 엔드포인트가 Yup을 사용해야 하며 입력을 수동으로 검증해서는 안 된다는 지침이 있다고 가정해 보겠습니다. 에이전트가 수동 가드를 작성하면 Abide는 다음과 같은 메시지를 반환할 수 있습니다.
Abide: 이 편집으로 인해 이 저장소의 지침에 있는 규칙을 위반한 것으로 보입니다.
- ~/.codex/AGENTS.md 65번째 줄의 "api-validation-uses-yup" 규칙:
"API 엔드포인트를 작성할 때 입력 검증을 수동으로 작성하지 마세요.
명확한 검증 메시지가 포함된 Yup과 API 핸들러의 조기 반환을 사용하세요".
(0.86)
지금 apps/web/src/pages/api/logout.ts를 수정한 다음 작업을 계속하세요.에이전트는 수정 요청을 받고 작업을 계속하기 전에 위반 사항을 해결할 수 있습니다. OpenCode에서는 편집 위반 사항이 도구 결과에 추가됩니다. 턴 수준 위반이 발생하면 턴이 끝난 후 후속 메시지가 하나 전송됩니다.
커밋되지 않은 변경 사항 수동 확인
훅과 동일한 방식으로 현재 커밋되지 않은 변경 사항을 평가하려면 check를 사용하세요.
abide check검사 범위를 좁히려는 경우 경로를 지정할 수도 있습니다.
abide check apps/web/src/pages/api/기존 코드 감사
audit 명령은 기존 파일을 새로 생성된 파일인 것처럼 평가합니다. 기존 저장소에 Abide를 도입할 때 유용합니다.
abide audit src/출력에는 규칙별 요약과 파일별로 정리된 목록이 포함됩니다. README에 따르면 실제 Next.js 애플리케이션의 API 라우트 33개를 감사하는 데 약 12초가 걸렸고 비용은 약 1센트였지만, 실제 결과는 저장소와 규칙에 따라 달라집니다.
규칙 활동 검토
보고서 명령을 실행하면 규칙, 실행된 규칙, 아직 한 번도 실행되지 않은 규칙을 확인할 수 있습니다.
abide report기계 판독이 가능한 출력을 얻으려면 --json을 추가하세요. check, audit, bench, calibrate에서도 JSON 출력을 사용할 수 있습니다.
규칙 타이밍과 판정 이해하기
컴파일된 각 규칙은 다음 두 단계 중 하나에서 실행됩니다.
- 편집 단계: 개별 편집 후 실행되며 해당 변경 덩어리를 평가합니다.
- 턴 단계: 턴이 끝날 때 한 번 실행되며, 턴 시작 시 생성된 스냅샷과 전체 diff를 비교해 평가합니다.
턴 수준 평가는 첫 번째 편집만으로는 답할 수 없는 질문에 중요합니다. 예를 들어 에이전트가 사용자가 요청하지 않은 기능을 추가했는지 여부가 이에 해당합니다. 턴이 끝나면 Abide는 셸 명령으로 생성된 변경 사항에도 편집 단계 규칙을 적용합니다.
판정은 다음 확률 구간으로 나뉩니다.
- 0.8 이상: 에이전트에 위반 사항을 수정하라는 지시가 전달됩니다.
- 0.5 이상 0.8 미만: 메모가 표시되지만 에이전트에 수정 지시는 전달되지 않습니다.
- 0.5 미만: 아무것도 표시되지 않습니다.
고급 워크플로
Git 기록을 기준으로 규칙 보정
문구가 좋지 않은 규칙은 서로 관련 없는 많은 변경 사항에서 중간 정도의 점수를 받아 유용한 결과를 전혀 내지 못할 수 있습니다. 보정 명령은 저장소의 Git 기록에서 가져온 최근의 실제 변경 덩어리에 대해 모든 규칙을 평가합니다.
abide calibrateAbide는 이 과정에서 최근 변경 덩어리 20개를 사용하며, 효과적으로 작동하지 않는 규칙을 끌 수 있습니다. 새로 컴파일한 평가 기준을 팀 전체에 적용하기 전에 결과를 검토하세요.
한 번도 실행되지 않는 규칙 조정
효과가 없는 규칙을 확인한 후에는 tune을 사용해 에이전트가 해당 규칙을 다시 작성하도록 할 수 있습니다.
abide tune각 평가 기준 항목에는 원본 지침이 인용되어 있으므로, 의심스러운 판정을 해당 판정을 만든 문구까지 추적할 수 있습니다. 일반적으로 기반 지침을 개선하면 관련 검사가 더 명확해집니다.
이전 에이전트 세션 재생
replay를 사용하면 지원되는 에이전트 중 하나의 과거 세션을 판정할 수 있습니다.
abide replay claude
abide replay codex
abide replay opencode앞으로 위반 사항이 발생할 때까지 기다리지 않고 이미 완료된 작업을 기준으로 평가 기준을 검토하는 데 유용합니다.
로컬 지연 시간과 비용 측정
벤치마크 명령을 실행해 자신의 컴퓨터에서 성능과 비용을 측정하세요.
abide bench저장소 보고에 따르면 13개 규칙을 검사할 때 입력 토큰은 약 1,000~1,600개, 검사당 비용은 약 $0.00004~$0.00007, Jev에서 소요 시간은 약 300밀리초입니다. 이 수치는 TypeSafe를 대상으로 직접 측정한 것이며 달라질 수 있으므로, 자신의 환경에서는 로컬 벤치마크를 기준으로 삼는 것이 좋습니다.
범위를 사용해 관련성 유지
.abide/rubric.json의 규칙에는 glob 기반 범위를 포함할 수 있습니다. 지침이 특정 파일에만 적용되는 경우 이러한 범위를 사용하세요. 예를 들어 검증 규칙은 API 라우트에 적용하고 스타일 규칙은 스타일시트로 제한할 수 있습니다. 범위를 좁히면 관련 없는 판정이 줄어들고 결과를 더 쉽게 이해할 수 있습니다.
개인정보 보호와 실패 동작
변경된 줄은 모든 호출에서 데이터 보존 기간을 0으로 요청한 상태로 사용자의 자체 키를 통해 TypeSafe로 전송됩니다. README에 따르면 데이터는 Abide가 운영하는 서버로 전송되지 않습니다.
Abide의 훅은 에이전트 세션을 중단하지 않도록 설계되었습니다. 훅 경로는 성공적으로 종료되고, 엄격한 기한을 사용하며, 호스트가 예상하는 내용만 출력합니다. 사용 가능한 키가 없거나 네트워크를 사용할 수 없는 경우 편집은 검사 없이 진행됩니다. 누락된 검사는 .abide/events.jsonl에 기록되며, abide report의 집계에도 포함됩니다.
Abide 제거
Abide가 설치된 모든 에이전트에서 Abide를 제거하세요.
abide uninstall하나의 통합만 제거하려면 에이전트 이름을 지정하세요.
abide uninstall codex프로젝트 수준 설치를 제거할 때는 --project를 추가하세요. 제거 작업은 Abide가 자체적으로 추가한 항목만 삭제합니다. 수동으로 삭제할 때까지 평가 기준 파일과 ~/.abide/.env는 그대로 둡니다.
결론
Abide는 자연어로 작성된 저장소 지침을 AI 코딩 세션 전체에서 실행되는 검사로 변환합니다. 적절한 훅을 설치하고 .abide/rubric.json을 컴파일 및 검토한 다음, 자동 검사, 감사, 보고서, 보정, 튜닝을 사용해 규칙을 효과적으로 유지하세요. 그 결과 기존 린터로는 표현할 수 없는 규칙을 위한 가벼운 적용 계층을 구축할 수 있습니다.