Think before coding
State assumptions, surface ambiguities, present multiple interpretations. No silent decisions.
How it comes together
Three perspectives, one framework
Works with
Claude Code
OpenCode
Any instruction-file tool
The problem
What unchecked AI coding assistants do
1
Start coding before clarifying ambiguous requirements
2
Add unrequested features, abstractions, and "improvements"
3
Expand scope mid-task: refactor while fixing, "improve" while adding
4
Silently rename files, change APIs, or rewrite working code
5
Skip verification until after the mistake is already in the diff
6
Suppress errors without telling you
7
Push to version control or delete files without warning
8
Run destructive CLI commands or modify secrets with no safety gate
9
Ship incomplete or stub implementations and call them done
10
Pick arbitrarily when rules conflict, choosing helpfulness over safety
How it works
Four core principles
Simplicity first
Minimum code that solves the problem. No speculative features, no unused abstractions.
Surgical changes
Touch only what you must. Match existing style. No scope creep hiding as cleanup.
Goal-driven execution
Define success criteria, loop until verified, report what changed and what remains unverified.
What makes this different
Beyond basic instructions
Core behavior
Four Core Coding Principles
Think before coding, prefer simplicity, make surgical changes, and define success through verification. These principles form the backbone that everything else builds on.
Collaborative Working Model
The human brings domain knowledge and architectural intent. The AI contributes speed, pattern recognition, critique, and exploration. Ideas are refined collaboratively before building.
Order of Precedence
Hard stops override everything unless you authorize. Explicit instruction overrides defaults. Safety overrides speed.
Three Named Operating Modes
Default, ambiguity, and cleanup modes give the AI an explicit behavioral model instead of leaving choices to chance.
Wording Conventions (Must / Should / May)
RFC-style rule weight removes ambiguity. Must and Never mean mandatory. Should and Prefer mean strong default. May means optional.
Shared Vocabulary / Interpretation Layer
Defined terms like "trivial task," "minor ambiguity," and "working code" mean you and the AI start from the same definitions.
Safety and execution control
Scope Control for Existing Code
Prevents touching adjacent code, expanding scope, rewriting working systems, or using cleanup as an excuse for unrelated changes.
Hard Stops with Rule Citation and Authorization Gate
When the AI cannot proceed, it names the specific rule that triggered the stop, creating a verifiable audit trail around dangerous actions.
Verification by Task Type with Manual Fallback
Bug fixes need reproduction. Features need interface checks. Refactors need before/after comparison. No automated tests? Define manual steps explicitly.
Broken Baseline Handling
If the baseline is already broken, the AI says so before changing code. No pretending everything is verified when it is not.
Reporting and maintenance
Structured Post-Task Report
After every non-trivial task: what changed, what was verified, what remains unverified, and problems noticed but left untouched.
Documentation Rules
Explain the why, not the what. Update docs when behavior changes. Avoid comments that merely repeat the code or rot faster than the implementation.
Deployment and reach
Full Multi-Dimensional Agnosticism
Works regardless of programming language, framework, AI tool, OS, domain, or project type. No dependencies referenced. Keep the global file universal.
Illustrative example
What the rules prevent vs. what they produce
Without CLAUDE.md
// You: "Fix the login bug"
AI rewrites the entire auth module
AI adds rate limiting you didn't ask for
AI renames variables across 12 files
AI catches an error and suppresses it
AI runs git push automatically
// 47 files changed. Bug still present.
With CLAUDE.md
// You: "Fix the login bug"
AI asks: "Is this the password or SSO flow?"
AI fixes the single validation function
AI reproduces the bug first, then makes it pass
AI reports: 1 file changed, verified, no side effects
// 1 file changed. Bug fixed. Verified.
How it differs
Feature comparison
| Feature | Karpathy | Bernstein | This repo |
|---|---|---|---|
| Core coding rules | Yes | Partial | Refined |
| Collaborative partnership framing | No | Yes | Refined |
| Order of Precedence | No | No | New |
| Operating modes | No | No | New |
| Must/Should/May wording conventions | No | No | New |
| Shared vocabulary / interpretation layer | No | No | New |
| Existing-code scope discipline | Partial | Partial | Formalized |
| Hard stops with rule citation | No | No | New |
| Hard-stop explanation protocol | No | No | New |
| Verification by task type | No | Partial | Formalized |
| Verification fallback to manual steps | No | No | New |
| Broken-baseline handling | No | No | New |
| Structured post-task reporting | No | No | New |
| Dedicated documentation rules | No | Partial | Formalized |
| Full multi-dimensional agnosticism | Partial | Partial | Made explicit |
Works everywhere
Fully agnostic by design
Programming language
Python, C, JS, TypeScript, C#, Java, Pascal, Rust…
Framework
React, Django, Qt, bare-metal…
Library
No dependencies referenced
AI tool
Claude Code, OpenCode, and adaptable to other instruction-file tools
OS
Windows, Linux, macOS
Domain
Web, embedded, desktop, scripts, data
Project type
New projects, legacy code, refactors
Verification method
Automated tests, manual validation, reproducible checks, baseline comparison
Common questions
FAQ
Yes. It works with any tool that reads instruction files: CLAUDE.md, AGENTS.md, GEMINI.md. Works natively with Claude Code and OpenCode. For other tools, follow that tool's convention. The content stays the same, only the filename changes.
No. Pure behavioral instructions in a Markdown file. Zero runtime impact. Zero dependencies. Zero configuration. It is a text file your AI tool reads before each session.
Override with explicit instruction. The framework respects your authority: explicit instruction always overrides defaults. You can also fork and modify the file to match your preferences.
No. It makes sessions faster by preventing rework. Every minute the AI spends asking before acting saves ten minutes undoing unwanted changes.
Structure matters. Operating modes, precedence rules, hard stops, and shared vocabulary create consistent behavior that ad-hoc prompts cannot. A prompt says "be careful." This file defines exactly what careful means, when to stop, and what to report.
Yes. Commit it to your repo as a project-level file. Everyone on the team gets the same guardrails and the same behavioral contract with their AI assistant. Consistency across developers, not just across sessions.
One file. 30 seconds. Every session better.
Install once. Benefit immediately. No configuration needed.
Andrej Karpathy (LLM coding observations)
Multica (CLAUDE.md adaptation)
David Scott Bernstein (partnership-driven style)
Zeljko Avramovic (systematization and expansion)