코드에는 linter가 있는데, 에이전트에 대한 지시에는 없었다

Claude Code나 Codex를 일상적으로 사용하다 보면, 리포지토리에 "에이전트에 대한 지시 파일"이 늘어갑니다. AGENTS.md, CLAUDE.md, 서브 에이전트 정의, 태스크 패킷(task packet)이나 handoff 문서 등입니다.

이것들은 에이전트의 거동을 직접적으로 좌우합니다. 그런데 내용이 비대해지거나, 모호한 참조("평소처럼", "기존 방식대로")를 포함하거나, 한 번 작성된 후 업데이트되지 않아 오래되면 에이전트의 거동은 조용히 불안정해집니다. 에러는 발생하지 않습니다. 다만, 서서히 정밀도가 떨어질 뿐입니다.

코드에는 linter나 formatter가 있는데, 이 지시 파일군에는 없었습니다. 그래서 만든 것이 katalint입니다.

pip install katalint
uvx katalint check

어떤 도구인가

katalint는 결정론적인(deterministic) linter입니다. 모델을 호출하지 않고, 네트워크에도 접속하지 않으며, 에이전트를 실행하지도 않습니다. 지시 파일을 정적으로 검사할 뿐입니다. 따라서 CI나 pre-commit에 안심하고 통합할 수 있습니다. 공개 인터페이스는 실질적으로 katalint check라는 하나의 명령어로 구성됩니다.

검출 결과는 다음과 같은 형태로 출력됩니다 (1행당 1개의 findings, text 또는 JSON).

AGENTS.md — warning KTL001 config/context-bloat (214 lines, limit 200)
.agent/tasks/fix.md — error KTL101 workflow/missing-acceptance-criteria
docs/agent/handoffs/h.md — error KTL103 workflow/missing-handoff-fields

v0의 규칙 (총 8종, 모델 호출 없음)

규칙은 "설정 파일의 냄새"와 "워크플로우의 냄새" 두 계통으로 나뉩니다.

설정 파일 (AGENTS.md / CLAUDE.md / 서브 에이전트 정의):

태스크 패킷 / handoff 문서:

설정 계통은 기본적으로 warning이며, 워크플로우 계통 중 완료 조건·검증·handoff 필드의 누락은 error입니다 (CI에서 걸러내기 쉽도록). 이 규칙들은 AGENTS.md / CLAUDE.md의 설정 실수를 정리한 공개 연구(arXiv:2606.15828)와 대응시키고 있습니다.

CI에 통합하기

GitHub Actions 등에서 uvx katalint check를 한 단계 실행하기만 하면 됩니다.

uvx katalint check

--format json을 붙이면 기계 판독 가능한 출력도 얻을 수 있습니다. inline suppression (이유 필수)이나 baseline 파일도 지원하므로, 기존 리포지토리에 나중에 도입하더라도 단계적으로 운영할 수 있습니다.

아직 v0.1입니다

이번 주에 PyPI에 막 공개하여 다운로드 실적도 이제 시작입니다. 규칙 추가 제안, 오탐(false positive) 보고, "우리 회사의 AGENTS.md에서는 이렇게 오검출되었다"와 같은 피드백을 환영합니다.

에이전트에게 코드를 쓰게 하는 시대에, 에이전트에 대한 지시 자체의 품질을 기계적으로 체크하는——그 공백을 메우는 도구로 키워나가겠습니다.

Discussion