바이브코딩을 하든 에이전트 코딩을 하든, 결국 AI가 일을 잘 하느냐는 CLAUDE.md를 얼마나 잘 썼느냐에 달려 있다. 이건 쓰면 쓸수록 중요성을 더욱 느낀다. 그런데 이 파일을 제대로 관리하는 게 생각보다 쉽지 않다. 효율 문제도 있고, 보안 문제도 있다.
효율부터 보면, "코드 잘 짜줘" 같은 모호한 지시를 넣으면 에이전트는 그냥 알아서 해석해버린다. 결과물이 들쭉날쭉해지는데 에러가 나는 것도 아니라서 뭐가 문제인지 모른다. 실패가 조용하다. Anthropic 공식 문서에서도 "Format code properly" 대신 "Use 2-space indentation"처럼 구체적으로 쓰라고 한다. 근데 파일이 길어지면 이런 모호한 표현이 어디 숨어있는지 눈으로 다 잡기가 어렵다.
보안 쪽은 더 무섭다. CLAUDE.md나 TOOLS.md 안에 API 키, 토큰을 그대로 넣어두고 커밋하는 경우가 생각보다 흔하다. AgentLinter 통계로 보면 워크스페이스 5개 중 1개에서 노출된 크리덴셜이 발견된다. .gitignore가 마크다운 안에 박혀있는 시크릿까지 잡아주진 않는다.
파일이 여러 개로 늘어나면 문제가 더 복잡해진다. SOUL.md에서는 "친절한 어시스턴트"라고 했는데 CLAUDE.md에서는 "간결하고 직접적인 톤"이라고 하면 에이전트가 혼란스러워한다. TOOLS.md에서 참조하는 파일이 실제로는 없다거나. 파일 5개 넘어가면 이런 모순이 3배 이상 늘어난다. 그래서 "CLAUDE.md도 코드잖아. 코드에 ESLint가 있듯이 이것도 린터가 있어야 하는 거 아닌가?" 하는 생각에 도구를 만들었다.
AgentLinter는 8가지 카테고리로 진단한다.
각각 0~100점으로 채점하고, 문제마다 구체적인 수정 제안을 준다. "be helpful" 같은 거 쓰면 "response length, tone, format을 명시하라"고 알려준다. API 키가 발견되면 즉시 로테이션하라고 CRITICAL로 띄운다.
100% 로컬에서 돌아가고 파일이 외부로 나가지 않는다. 에이전트 설정 파일에는 시스템 프롬프트, 보안 규칙, 개인 컨텍스트가 들어있을 수 있으니 이건 중요하다. 텔레메트리도 기본 꺼져있다. 전체 코드가 GitHub에 공개되어 있고 MIT 라이선스다. 100% 무료이다.
Claude Code뿐 아니라 Cursor, Windsurf, Clawdbot도 지원한다. 프로젝트에 CLAUDE.md만 있으면 프로젝트 모드로, AGENTS.md나 clawdbot.json이 있으면 에이전트 모드로 자동 전환해서 진단 범위를 조절한다.
설치는 한 줄이면 된다.
npx agentlinter
Node.js 18 이상이면 설정 파일 없이 바로 돌아간다. 한번 돌려보고 점수 확인해보시길.
해피 바이브코딩 & 해피 에이전트 라이프!
Website: https://agentlinter.com
GitHub: https://github.com/seojoonkim/agentlinter[
AgentLinter
AgentLinter - Linter for CLAUDE.md & AI Agents
Optimized for Anthropic's CLAUDE.md. Score, diagnose, and auto-fix your agent workspace files.
](https://agentlinter.com/)