Improving a Claude Code Config: A Practical Review

Improving a Claude Code Config: A Practical Review

I reviewed chris2ao/claude-code-config — a public Claude Code configuration with 8 rule files, MCP server setup, and a beginner guide. The guide itself is excellent. The config has real problems though. Here’s what I’d change and why, with drop-in replacements.

---

Problem 1: Rules That Don’t Change Behavior

The original has 8 rule files loaded into every session. Several — like “80% test coverage is MANDATORY” and “TDD is MANDATORY” — sound authoritative but Claude will ignore them the moment a user says “just write the function.” They burn context window tokens for no practical effect.

The fix: Only keep rules that genuinely shift Claude’s defaults. Cut everything else.

Improved: rules/coding-style.md

The original is solid. I’d tighten it:

# Coding Style

## Immutability
Create new objects instead of mutating existing ones. Return copies with changes applied, never modify in place.

## File Organization
- One concern per file. 200-400 lines typical, 800 max.
- Organize by feature/domain, not by type (don't group all controllers together).
- Extract when a file exceeds 400 lines.

## Error Handling
- Handle errors explicitly at every level.
- User-facing code: friendly messages. Server-side: log full context.
- Never silently swallow errors.

## Input Validation
Validate at system boundaries only — user input, external APIs, file contents. Trust internal code.

## Before Completing Work
- Functions under 50 lines, no nesting deeper than 4 levels
- No hardcoded values — use constants or config
- Readable names, no mutation

What changed: Removed the checklist format (Claude doesn’t literally run through checkboxes), removed redundant explanations, kept the actionable constraints that actually influence code generation.

Improved: rules/git-workflow.md

# Git Workflow

## Commit Messages

Format: `<type>: <description>`

Types: feat, fix, refactor, docs, test, chore, perf, ci

Keep the subject line under 72 characters. Use the body for context on *why*, not *what*.

## Before Committing
- No hardcoded secrets, API keys, or tokens
- No debug logging left in production code
- Changes are focused — one concern per commit

What changed: Removed the “Feature Implementation Workflow” section that mandated planner agents and TDD (those depend on a plugin, not built-in features). Kept the commit format, which genuinely changes Claude’s output.

Improved: rules/security.md

# Security

## Before Every Commit
- No hardcoded secrets (API keys, passwords, tokens in source)
- User inputs validated before processing
- Database queries parameterized (no string concatenation)
- HTML output sanitized

## Secret Management
Use environment variables or a secret manager. Never put secrets in source files.

## If a Secret Is Exposed
1. Stop work immediately
2. Rotate the exposed credential
3. Check git history — the secret persists in past commits even after deletion
4. Consider using `git filter-repo` to remove it from history

What changed: Cut the checklist from 8 items to 4 that Claude can actually verify in code. Removed vague items like “CSRF protection enabled” and “rate limiting on all endpoints” — Claude can’t verify those from a code review, and they depend entirely on the framework. Added the practical “secret exposed” protocol with the git filter-repo note.

Dropped: rules/testing.md

The original mandates TDD and 80% coverage. In practice:

• Claude doesn’t track coverage percentages
• Users rarely want the TDD red/green/refactor cycle forced on them
• If you want tests, ask for them — you don’t need a rule file

If you still want test guidance, put it in your project’s CLAUDE.md where it’s specific: “This project uses pytest. Run make test before committing. Aim for coverage on new code.”

Dropped: rules/agents.md

This references 9 agents and slash commands (/plan, /tdd, /code-review) that come from the everything-claude-code plugin. Without that plugin installed, this rule file causes Claude to hallucinate capabilities. If you use the plugin, its commands work without a rule file. Either way, this file does nothing useful.

Dropped: rules/hooks.md

The original describes hook types and warns about auto-accept. This is documentation, not a rule. Claude doesn’t need to be told how hooks work — it already knows. If you want hook guidance, it belongs in the README, not loaded into every session.

Improved: rules/performance.md

# Performance

## Context Window
When a conversation gets long, use `/compact` before starting new complex work. Avoid large refactors or multi-file features in the last 20% of context.

## Extended Thinking
Extended thinking is on by default. Toggle with Alt+T (Windows/Linux) or Option+T (macOS). Use Ctrl+O to see the thinking output.

What changed: Removed the “model selection strategy” section entirely. The original listed “Haiku 4.5”, “Sonnet 4.5”, and “Opus 4.5” — none of these are real model names. Claude Code handles model routing internally; a rule file doesn’t change which model runs your subagents. Kept only the context window advice, which is actually actionable.

Improved: rules/patterns.md

# Patterns

## Starting New Features
Search for existing templates, starter projects, or established patterns before building from scratch. Evaluate options before committing to one.

## Data Access
Encapsulate data access behind a consistent interface (repository pattern). Define standard operations (find, create, update, delete) so the storage backend can be swapped without changing business logic.

## API Responses
Use a consistent envelope:
```json
{ "success": true, "data": { ... }, "error": null, "meta": { "page": 1, "total": 42 } }

**What changed:** Minimal — this was already one of the better rule files. Trimmed verbosity.

---

## Problem 2: MCP Servers That Duplicate Built-in Features

The original recommends 5 MCP servers. Three of them overlap heavily with what Claude Code already does.

### What to Actually Use

| Server | Verdict | Why |
|--------|---------|-----|
| **Memory** | Skip | Claude Code has built-in persistent memory via `~/.claude/projects/` and auto-memory files. Adding a second memory system creates confusion about where knowledge is stored. |
| **Context7** | Keep | Genuinely useful — fetches live documentation for libraries. Claude's training data has a cutoff; this fills the gap. |
| **Sequential Thinking** | Skip | Claude already has extended thinking built in (up to 32K tokens). An external reasoning server adds latency for no benefit. |
| **GitHub** | Conditional | Only needed if you want Claude to create repos, manage issues, or search all of GitHub. For basic git operations (commit, push, PR), Claude Code's built-in tools + `gh` CLI are sufficient. |
| **Filesystem** | Conditional | Only needed if you need to access files *outside* the current project directory. Claude Code already has Read, Write, Edit, Glob, and Grep for everything inside the project. |

### Minimal MCP Setup

```bash
# The one server that adds genuinely new capability:
claude mcp add --scope user context7 -- npx -y @upstash/context7-mcp@latest

# Add GitHub only if you need full API access beyond basic git:
claude mcp add-json --scope user github '{"command":"npx","args":["-y","@modelcontextprotocol/server-github"],"env":{"GITHUB_PERSONAL_ACCESS_TOKEN":"YOUR_TOKEN"}}'

---

Problem 3: Plugin Dependency Without Disclosure

The original config builds heavily on the everything-claude-code plugin (agents, slash commands, workflows) but doesn’t clearly state that dependency. Someone cloning the repo and using just the rule files will get broken references.

The fix: Either remove all plugin-dependent content from rule files, or create a clear “Prerequisites” section that lists the plugin as required. I recommend the former — your rules should work standalone.

---

Problem 4: Windows-Only Hooks

The hook scripts (.ps1 files) only work on Windows/PowerShell. The guide presents them as a general setup.

The fix: If you want portable hooks, use shell scripts with a shebang:

#!/usr/bin/env bash
# .claude/hooks/log-activity.sh

input=$(cat)
tool_name=$(echo "$input" | jq -r '.tool_name // "unknown"')
timestamp=$(date '+%Y-%m-%d %H:%M:%S')
session_id=$(echo "$input" | jq -r '.session_id // "unknown"')

echo "[$timestamp] ($session_id) $tool_name" >> activity_log.txt

Then in .claude/settings.local.json:

{
  "hooks": {
    "PostToolUse": [{
      "matcher": "Bash|Edit|Write",
      "hooks": [{
        "type": "command",
        "command": "bash .claude/hooks/log-activity.sh",
        "async": true
      }]
    }]
  }
}

Or just provide both .ps1 and .sh versions and document which to use.

---

Problem 5: Context Window Budget

Loading 8 verbose rule files on every session is expensive. A simple “rename this variable” task shouldn’t cost thousands of tokens in security audit and TDD frameworks.

The fix: After the cuts above, you’re down to 4 lean rule files:

1. coding-style.md — Genuine style preferences
2. git-workflow.md — Commit format
3. security.md — Pre-commit safety checks
4. patterns.md — Architecture patterns

Heavyweight concerns (testing strategy, project-specific workflows, agent orchestration) belong in per-project CLAUDE.md files where they only load when relevant.

---

The Improved Structure

~/.claude/
  rules/
    coding-style.md    # Immutability, file org, error handling
    git-workflow.md    # Commit format, pre-commit checks
    security.md        # Secret detection, input validation
    patterns.md        # Repository pattern, API envelopes
  .gitignore           # Ignore-everything-then-whitelist
  README.md

4 files instead of 8. Each one earns its context window cost by changing Claude’s actual output. No phantom agent references, no fake model names, no documentation masquerading as instructions.

---

What the Original Got Right

Credit where it’s due:

• The COMPLETE-GUIDE.md is genuinely excellent. Line-by-line explanations with real-world analogies, aimed at beginners. This is the repo’s best asset.
• The .gitignore strategy (ignore-everything, whitelist what matters) is exactly right.
• The security pre-commit checklist concept is sound — the execution just needed trimming.
• The coding-style.md immutability rule actually changes Claude’s output. This is what a good rule looks like.

The repo is a solid starting point. The improvements above are about cutting fat, not changing direction.