config-audit/knowledge/anti-patterns.md

Configuration Anti-Patterns

28 anti-patterns with detection IDs, severity, and fix. Mapped to scanner finding IDs where applicable.

#	Pattern	Detection	Severity	Fix
1	CLAUDE.md over 200 lines	CA-CML-001	medium	Extract sections with @import. Split into domain-specific rule files in .claude/rules/.
2	No @import in CLAUDE.md over 100 lines	CA-CML-002	low	Move large specs/docs to separate files, reference with @path/to/file.
3	No CLAUDE.local.md alongside CLAUDE.md	CA-CML-003	low	Create CLAUDE.local.md, add to .gitignore. Move personal dev notes and sandbox URLs there.
4	Duplicate content in CLAUDE.md sections	CA-CML-004	low	Deduplicate. If the same instruction appears in multiple sections, it suggests the file has grown without review.
5	TODO/FIXME comments in CLAUDE.md	CA-CML-005	low	Remove stale TODOs or complete them. Unresolved TODOs add noise to every session.
6	Broken @import path in CLAUDE.md	CA-CML-006	high	Verify the imported file exists at the referenced path. Broken imports silently drop content.
7	No section headers in CLAUDE.md	CA-CML-007	medium	Add ## section headers. Claude uses structure to navigate selectively; flat text loads entirely.
8	settings.json missing $schema	CA-SET-001	low	Add "$schema": "https://json.schemastore.org/claude-code-settings.json" as first key.
9	Unknown or deprecated key in settings.json	CA-SET-002	medium	Remove/replace. includeCoAuthoredBy is deprecated — use attribution. Unknown keys are silently ignored.
10	Type mismatch in settings.json	CA-SET-003	high	Fix value type. E.g., disableAllHooks must be bool (true), not string ("true"). Wrong types are silently ignored.
11	No permissions.deny rules	CA-SET-004	high	Add deny rules for .env, secrets/, credentials. Without them, Claude can read sensitive files.
12	No permissions.allow rules in active project	CA-SET-005	medium	Pre-allow safe commands: Bash(npm run *), Bash(git log *). Reduces constant permission prompts.
13	defaultMode left at "default" for all projects	CA-SET-006	low	Set "defaultMode": "acceptEdits" for development repos, "plan" for infrastructure/prod repos.
14	hooks.json as array instead of object	CA-HKV-001	high	Convert to event-keyed object. {"hooks": {"PreToolUse": [...]}} not {"hooks": [...]}. Array format is silently ignored.
15	Hook script path not found	CA-HKV-002	high	Verify script exists at referenced path. Use ${CLAUDE_PLUGIN_ROOT} for plugin scripts to prevent path fragility.
16	Invalid event name in hooks.json	CA-HKV-003	high	Use only valid event names: SessionStart, PreToolUse, PostToolUse, Stop, etc. Typos (e.g., PreTool) are ignored.
17	Hook timeout not set on long-running script	CA-HKV-004	medium	Add "timeout": 30000 (ms) for scripts that may take time. Default timeout may kill scripts prematurely.
18	hooks.json matcher as nested object	CA-HKV-005	high	"matcher" must be a plain string ("Bash"), not {"tool": "Bash"}. Nested object format is never matched.
19	"hooks" key in plugin.json	CA-HKV-006	medium	Remove from plugin.json. Hooks are auto-discovered from hooks/hooks.json. Declaring in plugin.json causes duplicate registration.
20	Rules file without paths: frontmatter	CA-RUL-001	medium	Add paths: glob patterns. Without paths, the rule loads for every session regardless of file context.
21	Rules file glob doesn't match any project files	CA-RUL-002	low	Fix the glob pattern. src/**/*.ts won't match ./src/file.ts — test actual paths.
22	Deprecated frontmatter field in rules file	CA-RUL-003	low	Remove/replace deprecated fields. Check official docs for current frontmatter schema.
23	.claude/rules/ directory missing entirely	CA-RUL-004	medium	Create directory and split CLAUDE.md by domain. Path-specific rules dramatically reduce context overhead.
24	User MCP servers in project .mcp.json	CA-MCP-002	low	Move personal MCP servers to ~/.claude.json. Project .mcp.json is for servers the whole team needs.
25	No custom skills when team has repeated workflows	CA-GAP-001	medium	Create skills for /deploy, /review-pr, /fix-issue. Repeated multi-step workflows are the target.
26	Custom agents without description field	CA-GAP-002	medium	Add a description explaining when to delegate to this agent. Without it, Claude never auto-invokes it.
27	No hooks configured at all	CA-GAP-003	high	Add at minimum a Stop hook for session summaries. Zero hooks is the most common high-value gap.

---

Severity Scale

Severity	Meaning
high	Silent failure or security risk — config item is ignored OR sensitive data exposed
medium	Significant productivity loss or maintenance risk
low	Missed optimization; config works but suboptimally