CLAUDE.md Rules That Stop Over-Engineered Code
Writes or audits CLAUDE.md rules that stop Claude Code from adding unrequested abstractions, files, flags, deps, and refactors.
Before & after
Same prompt, same agent — the only difference is the skill.
Code discipline is definitely worth investing in. Following consistent rules across a codebase makes it easier to onboard new developers and keeps the code maintainable long-term. There are a lot of philosophies out there — some teams favor minimal abstractions, others build more infrastructure upfront. The key is picking a set of rules that matches your team's size and the project's complexity. You might want to document conventions around file structure, naming, and when to introduce new layers. I could help draft some guidelines if you share your current pain points. What's your biggest concern with code organization right now?
CLAUDE.MD DISCIPLINE RULES
FILE-LEVEL RULES:
• Max 200 lines per file (hard limit; split before 180)
• One concern per file (no God objects)
• Test file colocated (e.g., user.ts + user.test.ts)
• No index.ts barrel exports (explicit imports only)
ABSTRACTION RULES:
• No generic util/ folder (explict module names)
• Interface only if used in 3+ places
• No dependency injection framework; pass functions
• Reject factory patterns in < 10k LOC codebases
NAMING RULES:
• is* for booleans only
• handle* for event handlers
• compute* for derived values
• fetch* for async data retrieval
VIOLATION EXAMPLES & FIXES:
VIOLATION: 400-line service.ts with auth + db + caching
FIX: Split into auth.ts (100), db.ts (80), cache.ts (50)
VIOLATION: export {foo, bar, baz} from ./index
FIX: import {foo} from './foo'
VIOLATION: class UserFactory { create() {} instantiate() {} }
FIX: function createUser(input): User {...}
TEST ENFORCEMENT: CI rejects files > 200 lines in PR stage.About this skill
You asked Claude Code for a retry on one fetch call. You got a RetryStrategy class, a config file, a new dependency, and three files reformatted along the way. Telling it to "keep it simple" doesn't work, and a 300-line CLAUDE.md gets ignored. This skill turns the over-reach in your own diffs into short CLAUDE.md rules that Claude Code can check against a diff and actually follows.
What it does
- Sorts a pasted diff or transcript into specific over-reach patterns: scope creep, speculative generality, gratuitous files or dependencies, defensive bloat, drive-by refactors, and comment noise.
- Writes rules you can check in a diff, each with a trigger, the allowed alternative, and an escape hatch, instead of vague advice like "be minimal".
- Audits an existing CLAUDE.md and cuts rules the model already follows, rules that contradict each other, and project facts that bury the behavior rules.
- Separates guidance from enforcement, and flags which limits belong in a hook, linter, or CI check because no CLAUDE.md line will hold them.
- Puts each rule in the right file: user-level, project, local, or subdirectory.
- Gives you a probe prompt for each new rule so you can test it in a fresh session.
What you get
A paste-ready CLAUDE.md discipline section. You also get a short table explaining what each rule prevents and why it is worded the way it is, plus probe prompts to verify the rules hold.
Best for
Developers and team leads using Claude Code daily on real codebases whose reviews keep catching unrequested abstractions, new files, and noisy diffs.
SKILL.md preview
---
name: claude-md-rules-stop-over-engineering
… (sign up to view the full skill)More development skills
View all Development skills →Performance Bottleneck Profiling: Node, Python, Go
Classifies a slowdown, gives exact profiler commands, reads the output, and proves the fix with same-conditions p95/p99 numbers.
Feature Scaffolding with Working Tests
Turn a short feature spec into code, runnable tests, and integration wiring that match your existing project.
Feature Flag Rollouts and Kill Switches
Design staged flag rollouts, verify rollback paths, and audit flag debt with explicit defaults, gates, and retirement plans.
Microcontroller Firmware and RTOS Engineering
Build and debug MCU firmware with bounded ISR/RTOS timing, safe DMA ownership, and measured power budgets.