Whether you’re vibe coding or agent coding, how well the AI does its job ultimately comes down to how well you’ve written CLAUDE.md. The more I use it, the more I feel how important this is. But keeping this file in good shape is harder than you might think. There are efficiency issues, and there are security issues.
On the efficiency side, if you put in vague instructions like "write good code," the agent just interprets them however it wants. The results are inconsistent, but there’s no error, so you don’t know what’s wrong. The failure is silent. Even Anthropic’s official docs recommend being specific: "Use 2-space indentation" instead of "Format code properly." But as the file gets longer, it’s hard to catch every vague phrase by eye.
Security is scarier. Committing API keys and tokens directly in CLAUDE.md or TOOLS.md is more common than you might think. AgentLinter’s stats show exposed credentials in one out of every five workspaces. .gitignore won’t catch secrets embedded in Markdown.
Things get more complicated as the number of files grows. If SOUL.md says "friendly assistant" but CLAUDE.md says "concise, direct tone," the agent gets confused. Or TOOLS.md might reference a file that doesn’t actually exist. Once you have more than five files, these contradictions more than triple. So I built a tool, thinking, "CLAUDE.md is code too. If code has ESLint, shouldn’t this have a linter too?"
AgentLinter checks eight categories.
It scores each category from 0~100 and gives specific suggestions for fixing each issue. If you write something like "be helpful," it tells you to "specify response length, tone, and format." If it finds an API key, it flags it as CRITICAL and tells you to rotate it immediately.
It runs 100% locally, and no files leave your machine. This matters because agent configuration files can contain system prompts, security rules, and personal context. Telemetry is off by default too. All the code is public on GitHub under the MIT license. It’s 100% free.
It supports not just Claude Code, but Cursor, Windsurf, and Clawdbot too. If a project only has CLAUDE.md, it runs in project mode. If it has AGENTS.md or clawdbot.json, it automatically switches to agent mode and adjusts the scope of its checks.
Installation takes one line.
npx agentlinter
With Node.js 18 or later, it runs right away with no configuration file. Give it a run and check your score.
Happy vibe coding & happy agent life!
WebsiteAgentLinter — Linter for CLAUDE.md & AI AgentsOptimized for Anthropic's CLAUDE.md. Score, diagnose, and auto-fix your agent workspace files.AgentLinter · agentlinter.comOpenGitHubseojoonkim/agentlinterESLint for AI Agents — AGENTS.md/CLAUDE.md 채점·진단·자동수정 | Position Risk Warning · Token Efficiency · Security CheckGitHub · github.comOpen
