Hand-Writing Agents.md Significantly Improves AI Coding Stability

In an era where AI coding tools are increasingly widespread, many developers are used to letting AI generate everything automatically—including project configuration files. But a Bilibili creator, drawing on comparative experience from two real projects, offers a counterintuitive take: Agents.md must be hand-written. This isn't dogma; it stems from a deep understanding of how AI agents actually work.

Two Projects, Two Development Modes

The creator uses two projects he's currently developing as examples. The first is a high-performance video editor built on native Rust technology, supporting smooth 4K video scrubbing plus subtitle and opacity editing, with extremely high performance demands. The second is a card-based tower-defense game—a web multiplayer game with both frontend and backend, complex business logic and art assets, but relatively lower engineering difficulty.

These two projects differ not only in type but in development approach. The video editor uses semi-AI development: the creator carefully reviews every line of AI-generated code, manually modifying it or guiding adjustments through conversation, retaining the traditional programmer's hands-on habits. Even so, with AI assistance, this 30,000-line Rust project was completed in just three months—12 times faster than writing code by hand. The card game, by contrast, uses full-AI development: 99.9% of the code is generated directly by AI, producing 46,000 lines in 9 days, averaging 5,000 net-new lines per day—15 times more efficient than semi-AI mode.

The surge in speed brings a new problem: developers can no longer check code line by line—they can't even keep up with reading it. So how do you maintain memory and control over the project? The creator points out that the key is establishing shared memory between human and AI, and Agents.md and design documents are precisely the carriers of that memory.

Semi-AI development versus full-AI development differs primarily in the granularity of human review of AI-generated code. In semi-AI development, developers retain visibility into every line; AI plays the role of a high-speed typewriter while humans handle logical correctness and architectural decisions. Full-AI development shifts the review granularity from "lines" up to "features" and "documents," with humans intervening only at the requirements and acceptance levels. The risk of this granularity shift is that AI may introduce hidden assumptions or architectural drift during implementation that humans fail to notice—and since developers no longer read line by line, it's hard to catch these early. Therefore, full-AI development depends far more on documented context (Agents.md, design docs) than semi-AI mode; documentation becomes the human's only lever for oversight.

Agents.md vs. Skills: The Real Difference Is the Injection Mechanism

Many developers are confused about the difference between Agents.md and Skills. The creator explains that both are context injection, but the mechanisms are entirely different. Skills are dynamically injected: the agent sends the skill's description to the model, which judges based on the current task whether it's relevant and then decides whether to load the skill's body. This process is probabilistic and conditional. Agents.md, by contrast, is statically injected: in every single conversation, the agent injects the full Agents.md into the model's context—it's essentially a skill that's always active.

Because of this, Agents.md influences the model more frequently and more deeply. If poorly written, it becomes persistent context pollution. Conversely, if hand-written, Agents.md becomes a "contract" mutually recognized by human and model—the model reads it every turn, and the human knows exactly what's in it. If you let AI modify Agents.md automatically, the content may be scattered across hundreds of conversations, and the developer has no idea what was ultimately written. The creator's hand-written Agents.md is only 22 lines (barely a dozen lines excluding blanks), whereas AI auto-generation tends to balloon to 80 lines, causing a loss of shared memory.

Context injection refers to the process by which an agent, when calling a large language model (LLM), concatenates specific text into the model's input prompt, thereby influencing its output. Since LLM context windows are limited (commonly 8K to 200K tokens), what gets injected and how much directly determines whether the model has the information needed to complete the task. Common injection methods include system prompts, retrieval-augmented generation (RAG), and tool descriptions. Agents.md is essentially an engineered encapsulation of a system prompt, fixed in file form for easy version management and team collaboration. The key to understanding injection mechanisms is distinguishing "unconditional injection" from "conditional injection": the former occupies context space every turn, while the latter only loads when the model deems it relevant—a significant difference in context budget and stability impact.

Design Documents: The Second Cornerstone of Project Stability

Beyond Agents.md, the creator strongly recommends hand-writing project design documents or product requirements documents (PRDs). He shares a concrete case: the main character's nameplate in the game originally had a mouse-hover effect showing just a circle, and he wanted to change it to highlight the entire UI. So he wrote this requirement into the design doc and sent it to AI for execution.

On the surface this seems no different from typing directly into the chat box, but the impact on the project workflow is profound. If the feature gets accidentally broken days later, the developer can start a new conversation (or even switch models), paste the requirements doc, and have AI check whether the project conforms to it. The AI can accurately identify that the nameplate hover still shows a circle and pinpoint where to fix it. Design docs can also be used for self-checking contradictions and refined continuously as the project progresses.

The creator emphasizes that human memory is limited, but driving AI to work stably doesn't require remembering every detail. You just need to hand-write these two files—Agents.md and design docs—to give AI clear contextual guidance while keeping yourself in control of the project. For developers who aren't good at writing skills, skills can be delegated to AI, but these two files should be done personally.

Product requirements documents (PRDs) in traditional software engineering are contracts between product managers and development teams, describing functional behavior, boundary conditions, and acceptance criteria. In AI coding scenarios, the PRD's role has subtly shifted: it's not just for humans—it's for the model. When a developer pastes a PRD to AI and asks it to "check whether the project conforms to the document," the model is effectively performing a static review based on a natural-language specification. The effectiveness of this review depends on the document's precision—vague descriptions lead the model to make broad interpretations and miss issues. Therefore, design docs aimed at AI should use verifiable phrasing (e.g., "the entire UI highlights on mouse hover, not just the circular icon") and avoid subjective adjectives like "smooth experience." This aligns with traditional PRD writing principles, but in AI execution scenarios the payoff of precision is amplified.

Scope and Core Takeaway

The creator explicitly clarifies that this view doesn't apply to everyone. For small projects or throwaway scripts, letting AI auto-generate Agents.md is perfectly fine. But for complex, continuously iterating projects—especially for developers without formal CS training who use AI to get started—hand-writing Agents.md and design docs is an effective way to prevent projects from spiraling out of control.

The speed advantage of AI coding is certain, but speed also means the granularity of human oversight must adjust. From line-by-line review to document-driven development, the developer's role shifts from code editor to project architecture definer. Agents.md and design docs are the anchors of this shift—they are both the AI's context and the human's external brain for memory.