5.2 KiB
5.2 KiB
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 | MCP server with no trust level set | CA-MCP-001 | medium | Set "trust": "workspace" or "trusted" explicitly. Default is untrusted/sandboxed; may cause unexpected failures. |
| 25 | 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. |
| 26 | 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. |
| 27 | 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. |
| 28 | 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 |