A Single .md File Reduced AI Coding Errors from 41% to 3%

Why Does AI-Written Code Keep Falling Apart?

Everyone who has used AI for coding has encountered this dilemma: the code starts out fine, but then the AI writes increasingly messy code, fixes introduce more bugs, and everything spirals into a vicious cycle. Recently, a viral open-source project on GitHub offered an elegant solution — a mere 65-line .md file that has racked up 128,000 stars, making it the fastest-growing single-file repository.

This approach follows the coding principles of AI programming expert CAPACIT. The core idea is remarkably simple: use a rules file to constrain AI's behavioral boundaries. Real-world testing shows that just 4 basic rules can reduce AI coding errors from 41% to 11%, while the advanced 12-rule version drives the error rate down to just 3%.

The rules file mentioned here leverages the "system prompt injection" mechanism supported by modern AI coding tools (such as Cursor, Windsurf, GitHub Copilot, etc.). These IDE tools allow developers to place specific configuration files in the project root directory (like .cursorrules, .github/copilot-instructions.md, etc.), and the tools automatically inject the file contents as system-level prompts into every conversation with the AI. This means you don't need to manually repeat these rules each time — the AI remains constrained by them throughout the entire coding session.

Three Fatal Flaws of LLMs Writing Code

CAPACIT has long exposed the truth about LLM-based programming — the larger the model, the more likely the code is to collapse. The root causes lie in three fatal flaws:

First, making silent assumptions. AI won't proactively confirm requirements with you repeatedly. It acts on its own "understanding," and these assumptions often diverge completely from your actual intent. This happens because large language models are trained to "generate the most likely next token" rather than "confirm user intent" — models naturally tend to provide answers rather than ask questions.

Second, over-engineering. Something that could be done in 100 lines of code, the AI insists on writing 1,000 lines, introducing unnecessary abstraction layers and design patterns, turning simple problems into complex ones. This relates to the model's training data — it has seen extensive use of design patterns and architectural abstractions in enterprise code, and tends to over-apply these patterns in scenarios where they're unnecessary.

Third, modifying unrelated code. This is the most deadly — you ask it to fix one bug, and it casually refactors code it shouldn't touch, causing the entire system to crash.

According to real-world testing data, AI's native code-writing error rate reaches 41%, meaning nearly half our tokens and time are wasted cleaning up after the AI.

Four Golden Rules: Basic Rules Explained

The solution is absurdly simple — create a cloud.md file and set hard rules for the AI. The core consists of CAPACIT's four golden rules:

CAPACIT is an influential practitioner in the AI programming community. The core philosophy of his methodology stems from software engineering's "Principle of Least Privilege" and the "KISS Principle" (Keep It Simple, Stupid). The framework he proposed essentially transforms best practices traditionally applied to human developers into hard constraints for AI assistants. This approach is known as "structured constraint prompting" in the Prompt Engineering field.

Rule One: Think Before Coding

First, require the AI to list a requirements checklist. Only after you confirm with "OK" can it start writing code. Never let the AI make decisions for you. This rule directly addresses the "silent assumptions" problem.

Rule Two: Simplicity First

If the problem can be solved with minimal code, never write an extra line. Features that aren't needed, logic that won't be used — delete it all. This rule combats AI's instinct to over-engineer.

Rule Three: Surgical Modifications

Only modify code related to the task — no casual refactoring, no changing comments, no deleting unrelated code. The smaller the change, the lower the chance of things going wrong. This is the critical defense against AI "casually breaking things." In software engineering, this principle is similar to "Minimal Changeset" — each commit contains only modifications directly related to the current task, making code review and problem identification easier.

Rule Four: Goal-Oriented

Don't tell the AI step-by-step instructions like "first modify A, then modify B." Instead, directly tell it "after the changes, it must pass this test case." Use final acceptance criteria as constraints and let the AI figure out how to get there. This approach essentially transforms "procedural prompting" into "declarative prompting," giving the AI more implementation freedom while using results as the safety net.

With just these four basic principles, the error rate dropped from 41% to 11% — immediate, tangible results.

8 Advanced Rules: Error Rate Drops to 3%

After the basic version, developers conducted systematic testing across 30 codebases over 6 weeks, adding 8 advanced rules based on their findings:

1. Make judgments without rigid logic — Give AI decision-making space but set boundaries
2. Strictly control token consumption — Avoid lengthy, ineffective output. Tokens are the basic units that large language models use to process text — roughly 1-2 tokens per English word, and about 1-2 tokens per Chinese character. AI coding tools charge by token, so when AI produces verbose, ineffective output, it not only wastes time but directly increases costs. This rule essentially requires AI to output concise, goal-directed code.
3. Don't compromise on code conflicts — Insist on the correct implementation approach
4. Read the source code before making changes — Understand the context before modifying
5. Reject fake tests — Don't allow tests written merely to pass rather than verify functionality. "Fake tests" refer to test cases where AI hard-codes expected results or skips critical assertions just to satisfy the "tests pass" requirement — these tests show green lights on the surface but provide zero actual protection.
6. Set checkpoints for each step — Break large tasks into smaller pieces, verify progressively
7. Strictly follow code style — Maintain project consistency
8. Never hide problems — Require AI to proactively expose uncertainties

Using all 12 rules in combination directly reduced the error rate from 41% to 3%, while maintaining a 76% rule compliance rate. This means the AI follows the constraints in the vast majority of cases.

Core Insight: Proactive Guidance Beats Reactive Fixes

The success of this project reveals an important AI programming paradigm: Rather than spending enormous time fixing AI's erroneous output, it's better to set clear behavioral boundaries at the input stage.

The cloud.md file is essentially an "AI programming constitution." It doesn't require complex engineering architecture or additional toolchains — just 65 lines of plain text can significantly improve AI coding reliability. This "rules as engineering" approach is worth adopting for every developer using AI coding tools. This is also an emerging consensus in the Prompt Engineering field — the most effective way to manage AI isn't a better model, but a better constraint framework.

For non-technical users, this case also illustrates an important truth: The key to harnessing AI isn't technical ability, but whether you can clearly define rules and boundaries. Whether in programming or other AI application scenarios, proactive guidance and constraints are always more efficient than after-the-fact fixes.