Engineering Discipline — LLM Coding Guidelines

A single CLAUDE.md file with 10 engineering discipline rules — an enhanced version of Andrej Karpathy's 4 behavioral guidelines for LLM coding. Tool-agnostic — works across Claude Code, Codex, Cursor, WorkBuddy, and any LLM coding assistant.

English | 简体中文

Why This Exists

Karpathy's original 4 rules (Think Before Coding, Simplicity First, Surgical Changes, Goal-Driven Execution) are a great start. This enhanced version expands them to 10 rules — adding verification, debugging, dependency management, communication, and self-audit — to teach the model how to verify itself, not just how to write.

"These are not suggestions. These are rules. Follow them and you'll produce code that doesn't need to be rewritten." — Andrej Karpathy

Enhancement Comparison: 4 Rules vs 10 Rules

Metric	Original 4 Rules	Enhanced 10 Rules	Improvement
Rule count	4	10	+150%
Engineering dimensions covered	1 of 6 (16.7%)	6 of 6 (100%)	+500%
LLM failure modes covered	3 of 11 (27.3%)	11 of 11 (100%)	+267%
Execution phases	1 (coding only)	4 (Pre → In → Post → Audit)	+300%

Coverage by Engineering Dimension

Dimension	4 Rules	10 Rules
Coding Discipline (think, simplify, surgical, goal)	✅ Full	✅ Full
Verification (verify before reporting)	❌	✅ Full
Debugging (systematic, reproduce-then-fix)	❌	✅ Full
Dependency Management (pin, audit, minimize)	❌	✅ Full
Communication (clear commits, flag concerns)	❌	✅ Full
Self-Audit (review own work before declaring done)	❌	✅ Full

LLM Failure Mode Coverage

Failure Mode	4 Rules	10 Rules
Silent assumptions	✅	✅
Over-engineering	✅	✅
Unnecessary diff noise	✅	✅
Unclear success criteria	✅	✅
Claims success without verification	❌	✅
Guessing instead of debugging	❌	✅
Bloated dependencies	❌	✅
Vague commit messages	❌	✅
Kitchen Sink anti-pattern	❌	✅
Wrong Abstraction	❌	✅
Runaway Refactor	❌	✅

Bottom line: The original 4 rules teach an LLM how to write code. The enhanced 10 rules also teach it how to verify, debug, communicate, and self-audit — covering 4× more failure modes.

The 10 Rules at a Glance

#	Rule	What It Prevents
1	Read Before You Write	Alien code that doesn't match the codebase
2	Think Before You Code	Silent assumptions, hidden tradeoffs
3	Simplicity	Over-engineering, premature abstraction
4	Surgical Changes	Unnecessary diff noise, style drift
5	Verification	Code that seems to work but doesn't
6	Goal-Driven Execution	Vague tasks, unclear success criteria
7	Debugging	Guessing instead of investigating
8	Dependencies	Bloated package manifests, unnecessary deps
9	Communication	Unclear commit messages, unflagged concerns
10	Common Failure Modes	Kitchen Sink, Wrong Abstraction, Runaway Refactor, etc.

The Four Phases

┌─────────────────────────────────────────────┐
│  Pre-flight    →  Surface assumptions       │
│                   State the plan             │
│                  (Rule 2, Rule 6)            │
├─────────────────────────────────────────────┤
│  In-flight     →  Rules 1-4 for writing     │
│                   Rule 8 for dependencies   │
├─────────────────────────────────────────────┤
│  Post-flight   →  Rule 5 (verification)     │
│                   Rule 7 (if debugging)      │
│                   Rule 9 (communication)     │
├─────────────────────────────────────────────┤
│  Self-audit    →  Rule 10 failure modes     │
│                   before declaring done      │
└─────────────────────────────────────────────┘

Before & After

Without rules (common LLM behavior)

User: "Add a search feature to the user list"

LLM without guidelines:

• Creates a new SearchService class with 3 layers of abstraction
• Adds lodash, fuse.js, and rxjs as dependencies
• Refactors the existing UserList component to use the new service
• Changes 8 files, 400+ lines of diff
• ✅ Search works... but the PR is a nightmare to review

With rules applied:

Rule	What Changes
Rule 2 (Think Before You Code)	LLM states: "I'll add a filter function to the existing UserList. No new deps needed."
Rule 3 (Simplicity)	Uses the existing useState + filter() — 15 lines, not 400
Rule 4 (Surgical Changes)	Only touches UserList.tsx — no drive-by refactoring
Rule 8 (Dependencies)	Zero new dependencies added
Rule 5 (Verification)	Runs the existing test suite before declaring done

Result: 1 file changed, 15 lines added, 0 new dependencies, clean PR.

Another example: Bug Fix

Without rules: LLM guesses at the fix, adds a try/catch to suppress the error, and marks it "fixed."

With rules applied:

1. Rule 7 (Debugging) — Reproduce the error first: "The crash happens when user.profile is null"
2. Rule 5 (Verification) — Write a test that reproduces the bug, then fix it so the test passes
3. Rule 4 (Surgical Changes) — Only change the null check, don't refactor the whole function
4. Rule 9 (Communication) — Commit message: "Fix null pointer when user.profile is undefined"

---

Install

Option A: Claude Code Plugin (recommended)

From within Claude Code, first add the marketplace:

/plugin marketplace add murphycheng-24/coding-guidelines

Then install the plugin:

/plugin install engineering-discipline@coding-guidelines

This installs the guidelines as a Claude Code plugin, making the skill available across all your projects.

Option B: CLAUDE.md (per-project)

New project:

curl -o CLAUDE.md https://raw.githubusercontent.com/murphycheng-24/coding-guidelines/main/CLAUDE.md

Existing project (append):

echo "" >> CLAUDE.md
curl https://raw.githubusercontent.com/murphycheng-24/coding-guidelines/main/CLAUDE.md >> CLAUDE.md

Option C: Cursor

Copy .cursor/rules/engineering-discipline.mdc into your project's .cursor/rules/ directory. See CURSOR.md for details.

Using with Other Tools

These rules are tool-agnostic:

Tool	How to Use
Claude Code	Place CLAUDE.md in project root
Cursor	Use .cursor/rules/engineering-discipline.mdc
Codex (OpenAI)	Include in system prompt or project instructions
WorkBuddy	The skill loads rules into context automatically

The rules work because they constrain universal LLM failure modes — silent assumptions, over-engineering, style drift, scope creep — which are not tool-specific.

How to Know It's Working

These guidelines are working if you see:

• Fewer unnecessary changes in diffs — Only requested changes appear
• Fewer rewrites due to overcomplication — Code is simple the first time
• Clarifying questions come before implementation — Not after mistakes
• Bug fixes verified by reproducing tests — Not hopeful guessing
• Clean, minimal PRs — No drive-by refactoring or "improvements"
• Specific commit messages — "Fix null pointer in user lookup" not "Fix bug"

Customization

These guidelines are designed to be merged with project-specific instructions. Add them to your existing CLAUDE.md or create a new one.

For project-specific rules, add sections like:

## Project-Specific Guidelines

- Use TypeScript strict mode
- All API endpoints must have tests
- Follow the existing error handling patterns in `src/utils/errors.ts`

Repository Structure

.
├── .claude-plugin/
│   └── plugin.json                     # Claude Code plugin config
├── .cursor/
│   └── rules/
│       └── engineering-discipline.mdc  # Cursor IDE rule
├── skills/
│   └── engineering-discipline/
│       └── SKILL.md                    # Reusable skill definition
├── CLAUDE.md                           # Core guidelines (the 10 rules)
├── CURSOR.md                           # Cursor setup guide
├── CONTRIBUTING.md                     # Contribution guidelines
├── CHANGELOG.md                        # Version history
├── README.md                           # This file
├── README.zh.md                        # Chinese README
├── LICENSE                             # MIT
└── .gitignore

Tradeoff Note

These guidelines bias toward caution over speed. For trivial tasks (simple typo fixes, obvious one-liners), use judgment — not every change needs the full rigor.

The goal is reducing costly mistakes on non-trivial work, not slowing down simple tasks.

License

MIT © murphycheng-24