祝融说。 Chapter 3 Leave No Room for Doubt: Using Markdown to Establish AI's Single Source of Truth

Chapter 3 Leave No Room for Doubt: Using Markdown to Establish AI's Single Source of Truth

2026.08.10

You might find it odd that, in a book about cutting-edge AI programming, we are devoting an entire chapter to "writing documentation" — something that sounds utterly traditional, even a bit "old-fashioned."

The answer is simple: in the AI era, the value of documentation has undergone a nuclear-level leap.

In the past, documentation was "written for people to read." Its main purpose was knowledge transfer within the team and project handover. It mattered, but it had no direct impact on the "execution" of code. A programmer could fully understand and modify a system without reading any documentation at all, relying purely on the code itself (though this is usually the beginning of a disaster).

Now, the situation is completely different. Documentation in the AI era is, first and foremost, "written for machines to read." It is no longer an "accessory" to the code, but the "law" and "generation instruction" of the code. It has evolved from a passive "instruction manual" into an active "constrainer."

A well-maintained project document is to the AI what the "laws of Newtonian mechanics" are to the physical world. It is not a "suggestion" but a foundational rule that must be obeyed and that constitutes the AI's working premises. When you repeatedly reference this document in your conversations, it occupies a prominent place in the context and usually outweighs scattered verbal agreements. (This is not a strict technical account of the model's attention weights; it is a useful engineering analogy.)

In this chapter, we will completely change how you think about "writing documentation." You will learn to stop treating it as a burden and instead embrace it as the most powerful "reins" you have for steering the AI.

3.1 Why Must We Maintain Project Documentation? (Instead of Relying on Conversation History)

Before we begin building documentation, we must first thoroughly demolish a dangerous illusion — many people believe that, since AI has an extremely long context memory, they only need to state a few rules at the start of a conversation and the AI will remember them forever. Why go to the extra trouble of maintaining external documentation?

This mindset is the number one culprit behind AI programming projects descending into chaos and spinning out of control. Relying on conversation history is like building your skyscraper on sand.

The Five Deadly Flaws of Conversation History

1. Volatile and Contaminable Memory

Conversation history is volatile. A single accidental browser refresh, a network interruption, or your own decision to clear the session (a necessary operation, as we will discuss later) instantly wipes out all context. Like an amnesiac, you will have to re-describe your entire project to the AI from scratch — a process that is both inefficient and highly error-prone.

Worse still, conversation history is extremely susceptible to contamination. In the course of solving a complex problem, you and the AI will do a great deal of trial and error and wander down many wrong paths. These failed attempts, rejected solutions, and debug console.log statements will remain in the conversation history as "garbage" forever. When the AI later generates code, this garbage acts like "background noise," interfering with its judgment and potentially causing it to resurrect an idea that was already proven wrong.

Real-World Comparison

Relying on conversation history: You ask the AI to fix a bug. After a twenty-round conversation, the bug is finally fixed. Two days later, you start a new feature. While generating code, the AI unconsciously reintroduces a temporary variable name from the earlier bug-fixing process, because in its contaminated context it considers that name "important."
Relying on project documentation: You fix the bug. Then you record in CHANGELOG.md: "Version 1.2.1: Fixed a state inconsistency caused by asynchronous updates. Core solution: migrated the state update from useEffect to an event callback." When you start the new feature, you simply have the AI re-read this clean, conclusive document.

2. Lacks Authority and a Global View

Conversation history is linear and local. It records only the "back-and-forth" exchange between you and the AI. It cannot convey the "full picture" or the "final state" of a project.

When a project grows complex and spans multiple modules, you may discuss different parts with the AI at different points in time.

On Monday, you settled the database table structure with it.
On Wednesday, you discussed the selection of a frontend UI component library.
On Friday, you designed the backend API interfaces.

These three conversations are scattered across a long history. When, the following Monday, you ask the AI to write a feature that involves frontend-backend interaction, can it accurately integrate these three "isolated" snippets of memory? The answer is: with great difficulty. It will very likely forget the UI library settled on Wednesday and generate code with another library it is more "familiar with."

Project documentation, by contrast, offers an authoritative, global perspective. ARCHITECTURE.md is the project's "constitution." Wherever and whenever, it lays down the final designs of the database, the UI library, and the APIs in a definitive, unquestionable form. Before every action, the AI must return here to "consult the code," rather than dig through the noisy "records of courtroom debates."

3. A Collaboration Nightmare

If your project involves more than one person, relying on conversation history directly causes collaboration to collapse.

Your conversation history is your personal "private property." Other team members cannot access it, nor can they understand the "tacit understanding" and "agreements" you reached with the AI. When your colleague B picks up your work and opens a fresh session, the AI is a blank slate to them. They may have the AI generate code that completely violates the conventions you previously established, or use a third-party library you explicitly banned.

Project documentation, in contrast, is the team's shared "public contract." Anyone — human or AI — must read it on day one of joining the project. It ensures that the entire team (including every human and AI instance) holds a fully consistent understanding of the project's core rules. This is what makes large-scale, multi-person collaborative AI development possible.

4. Cannot Be Version-Controlled

Conversation history cannot be version-controlled. You have no way of knowing how the important architectural decision you settled on with the AI one afternoon two weeks ago differs from today's version. When something goes wrong and you need to trace and investigate, combing through tens of thousands of lines of conversation is an impossible task.

Project documentation (.md files), on the other hand, is part of the code. It can, and must, be brought under Git version control just like your .js and .go files.

You can clearly see in which commit we migrated the database from MySQL to PostgreSQL.
You can compare the ARCHITECTURE.md across branches to review the soundness of an architectural change.
When a newly onboarded AI (or an intern) breaks the system, you can use git blame to quickly pinpoint which documentation change introduced the misleading information.

Treating documentation as code is the core competency of an engineer in the AI era.

5. Loss of the Power to "Force Reset"

As we discussed in Chapter 1, the most effective weapon against the AI's "confirmation bias" is to decisively clear the session (/clear) and forcibly "reset" its thinking.

If you depend on conversation history, you are trapped in a dilemma:

Don't reset: let the AI sink ever deeper down the wrong path.
Reset: lose all context and be forced to start over from scratch.

As a result, you dare not — and cannot — wield this most powerful corrective tool.

With project documentation, you gain the ultimate "freedom." You can execute /clear anytime, anywhere, with no psychological burden whatsoever, because you know that all of the project's "memory in essence" has been safely and structurally preserved in those few Markdown files. After the reset, all you need is one simple instruction: "Please re-read all .md documents in the project root directory, and based on the latest entries in CHANGELOG.md, continue our previous work."

The AI is instantly restored to full strength, returning to a "factory-default" state that is the most lucid, the most focused, and entirely free of contamination from historical junk.

Conclusion: Abandon all illusions about conversation history. It is not your asset; it is your liability. Starting today, cultivate an iron discipline: any important decision, any core rule, any stage-level achievement must be distilled into your project documentation the moment it happens.

Let documentation be the only, the eternal, the unshakeable "single source of truth" between you and the AI.

3.2 Three Essential Documents and Their Templates: `CLAUDE.md`, `ARCHITECTURE.md`, `CHANGELOG.md`

Now that the theory is clear, let us turn to practice. A complex commercial project may require many kinds of documentation. But based on my hands-on experience, three documents are absolutely indispensable; together, they form the "troika" of the AI constraint system.

I use the AI model I work with most often, Claude, as an example and name one of the documents CLAUDE.md. You can adjust it to match the model you use (e.g., GPT4.md).

The three documents are:

CLAUDE.md (or AGENTS.md): AI behavior guidelines and role setting. This is the AI's "employee handbook," defining what it may do, what it may not do, and the role it should play.
ARCHITECTURE.md: Project architecture and technical-decision blueprint. This is the project's "technical constitution," recording all key technical choices, design patterns, and interface contracts.
CHANGELOG.md: Project evolution and state-memory log. This is the project's "voyage log," enabling the AI to "recall" at any moment what the project has accomplished and what stage it is in.

Let us examine how to create and maintain each of them.

1. `CLAUDE.md`: The AI's "Employee Handbook"

The core goal of this document is to give the AI a clearly defined "persona" and a set of inviolable "behavioral red lines." It dramatically reduces the "filler" and "uncertainty" in the AI's interactions, making its behavior resemble that of a professional, well-trained engineer.

What should this document contain?

Role and Identity: What role do you want the AI to play? A senior frontend architect? A backend expert fluent in Go? A clearly defined role activates the AI's knowledge weights within that specific domain.
Core Directives: Global commands that apply throughout the project. For example, "Code must be in English," "All code blocks must specify their language," "Do not say 'I am just a language model,'" and so on.
Tech-Stack Constraints: Extremely important! Here, you must list, in the most precise terms, every technology permitted in the project along with its version number. This effectively prevents the AI from "taking liberties" and introducing incompatible libraries.
Absolute Prohibitions: List the things the AI is absolutely never allowed to do, under any circumstances. For example, "Never access the network," "Never use the any type," "Never manipulate the DOM directly inside UI components," and so on.
Output-Format Requirements: How do you want the AI to format its responses? For example, provide a short written explanation before offering code, or always wrap file paths in code blocks.

Template: CLAUDE.md

# AI Agent Directives: Project "Phoenix"

This document defines your role, rules, and constraints for working on Project "Phoenix". You must adhere to these directives in all your responses.

## 1. Persona: Senior Full-Stack Engineer

You are a Senior Full-Stack Engineer with 10 years of experience in building complex, cross-platform enterprise applications. Your expertise lies in Go for the backend and TypeScript/React for the frontend. You value clean code, robust architecture, and comprehensive testing.

## 2. Core Directives

- Language: All code, comments, and commit messages must be in English.
- Clarity over cleverness: Write simple, self-explanatory code. Avoid obscure language features.
- No Apologies: Do not apologize or state that you are an AI. Be confident and direct.
- Code Blocks: All code snippets must be enclosed in markdown code blocks with the correct language identifier (e.g., ```go, ```typescript).
- Assume I have context: Do not repeat large blocks of code from our previous conversation unless I ask you to.

## 3. Tech Stack Constraints (The ONLY allowed technologies)

## Backend
- Language: Go (version 1.21)
- Web Framework: Gin (v1.9.1)
- Database: PostgreSQL 15
- ORM: GORM (v1.25.5)
- Testing: Go's built-in testing package. No third-party testing frameworks.

## Frontend
- Language: TypeScript (v5.1)
- Framework: React (v18.2)
- State Management: Zustand
- Styling: Tailwind CSS
- Build Tool: Vite

## 4. Absolute Prohibitions (Things you must NEVER do)

- DO NOT access the internet or any external real-time information.
- DO NOT use the `any` type in TypeScript. Use `unknown` for type-unsafe values and perform explicit type checking.
- DO NOT write API calls (`fetch`, `axios`) directly inside React components. All data fetching logic must be encapsulated in custom hooks (e.g., `useUserData`).
- DO NOT use default exports (`export default`). Always use named exports (`export const ...`).
- DO NOT suggest any new libraries or technologies not listed in the Tech Stack Constraints. If a task seems impossible with the current stack, state that and ask for clarification.

## 5. Output Formatting

- When providing code, first give a brief, one-sentence explanation of the change.
- When creating a new file, always provide the full file path, e.g., `// src/components/UserProfile.tsx`.
- If you need me to make a decision, present the options as a numbered list with pros and cons for each.

---
By acknowledging this document, you agree to act as a professional engineering partner on Project "Phoenix".

2. `ARCHITECTURE.md`: The Project's "Technical Constitution"

If CLAUDE.md governs "behavior," then ARCHITECTURE.md governs "structure." It defines the macro design of the project and serves as the "blueprint" that every module and piece of code must follow.

What should this document contain?

Project Overview: A few sentences explaining what the project does and what its core goal is.
Architecture Diagram: If possible, use Mermaid.js or ASCII art to sketch a simple architecture diagram showing the relationships among the major modules (frontend, backend, database, cache). This is very helpful for the AI's "macro understanding."
Core Design Patterns: The key design principles the project follows. For example, "All APIs must be RESTful," "Adopt a layered architecture," "State changes must follow a unidirectional data flow."
Directory-Structure Conventions: Clearly define how the project's files and directories should be organized. This keeps the AI from creating files at will and turning the structure into chaos.
API Contract: Define the API conventions for frontend-backend interaction, including URL-naming rules, request methods, data formats, error codes, and so on.
Data Models: Define the core business entities and their data structures, such as User, Product, and Order.

Template: ARCHITECTURE.md

# Project "Phoenix" - Architecture Document

This document is the Single Source of Truth for the architecture of Project "Phoenix". All code must conform to the principles outlined here.

## 1. Project Overview

Project "Phoenix" is an internal dashboard for managing customer support tickets. It allows support agents to view, update, and close tickets.

## 2. Architecture Diagram (High-Level)

```mermaid
graph TD
 A[Browser/Frontend] -- HTTPS/JSON --> B(Backend API - Go/Gin);
 B -- SQL --> C(PostgreSQL Database);
```

## 3. Core Design Principles

- Layered Architecture: The application is strictly divided into three layers. There should be no cross-layer imports.
  - Presentation Layer (React Components): Responsible for UI only. "Dumb" components.
  - Business Logic Layer (React Hooks / Go Services): Handles application logic and state.
  - Data Access Layer (Go Repositories): Communicates with the database.
- Stateless Backend: The Go backend API must be stateless. All session/user state is managed by the client using JWTs.
- Unidirectional Data Flow (Frontend): React components follow a unidirectional data flow. State flows down, events flow up.

## 4. Directory Structure

```
/
├── backend/
│ ├── api/ # Gin handlers
│ ├── cmd/ # Main application entrypoint
│ ├── internal/
│ │ ├── model/ # GORM models
│ │ ├── repository/ # Data access logic
│ │ └── service/ # Business logic
│ └── go.mod
└── frontend/
 ├── public/
 ├── src/
 │ ├── api/ # API client functions
 │ ├── components/ # Reusable UI components
 │ ├── hooks/ # Custom React hooks (Business Logic)
 │ ├── pages/ # Page-level components
 │ └── App.tsx
 └── package.json
```

## 5. API Contract

- Endpoint Naming: All endpoints are plural nouns, e.g., `/api/v1/tickets`.
- Authentication: All requests to `/api/v1/*` must include an `Authorization: Bearer <JWT>` header.
- Standard Success Response (200 OK):
  ```json
  {
    "success": true,
    "data": { ... }
  }
  ```
- Standard Error Response (4xx/5xx):
  ```json
  {
    "success": false,
    "error": {
      "code": "ERROR_CODE",
      "message": "A human-readable error message."
    }
  }
  ```

## 6. Core Data Models

## Ticket
- `id`: UUID (Primary Key)
- `title`: string
- `description`: text
- `status`: string (`'open'`, `'in_progress'`, `'closed'`)
- `priority`: string (`'low'`, `'medium'`, `'high'`)
- `created_at`: timestamp
- `updated_at`: timestamp

3. `CHANGELOG.md`: The Project's "Voyage Log"

This document is the simplest, and the easiest to overlook, yet in daily development it plays a crucial role as a "memory anchor." Its core goal is to solve the AI's problem of "forgetting where we left off."

Every time you complete an important feature, fix a critical bug, or make a decision that will affect subsequent development, you should take ten seconds to record it here.

What should this document contain?

Version number/date: Identifies the point in time of the entry.
Concise description of the change: One sentence explaining what was done.
(Optional) Key decisions or context: If a change rests on an important discussion or decision, briefly note it here as a "memory clue" for the AI.

Template: CHANGELOG.md

# Changelog - Project "Phoenix"

This log tracks the development progress and key decisions.

2023-10-27

- Implemented: User authentication endpoints (`/login`, `/register`) are complete on the backend. JWT generation and validation logic is in place.
- Decision: Frontend will store the JWT in `localStorage` for this internal tool. Security implications are accepted.
- Next Step: Begin work on the frontend login page.

2023-10-26

- Completed: Backend project setup with Gin and GORM.
- Completed: Database schema for `users` and `tickets` tables defined in `backend/internal/model`.
- Established: Initial connection to the PostgreSQL database is working.

---

How to use these three documents?

It is simple. Every time you start a new development session, or after running /clear to reset, your first instruction should always be:

"Please read and fully acknowledge the rules and context from CLAUDE.md, ARCHITECTURE.md, and CHANGELOG.md. Based on the latest entry in the changelog, our next task is to build the frontend login page. Let's start by creating the file frontend/src/pages/LoginPage.tsx."

This instruction is like a "system startup disk": it instantly loads all of your project's core rules, complete architecture, and latest progress into the AI's mind. It transforms a "general-purpose" large model into a "domain expert" dedicated to your project.

3.3 How to Write Constraint Instructions That AI Understands and Will Not Dare Defy

With the documentation skeleton in place, we also need to master how to fill it in. Writing constraint instructions for an AI is an art, and it differs fundamentally from writing documents for humans. Humans can tolerate vagueness, implicitness, and allusion; AI requires precision, freedom from ambiguity, and language that approaches the logic of code.

Here are five core principles for writing effective constraint instructions:

1. Use Imperative Sentences and Modal Verbs

Do not write in a suggestive or descriptive tone; write in a commanding tone.

Vague (weak constraint): "It would be good if we use named exports."
Precise (strong constraint): "You must always use named exports (export const ...). Do not use default exports (export default)."

Words such as Must, Must not, Always, Never, and Do not dramatically raise the weight of an instruction in the AI's model.

2. Provide Positive and Negative Examples

Saying only "what not to do" is not enough; it is best to provide an example of "how to do it correctly." This helps the AI learn and match the pattern you want more quickly.

Vague: "Avoid complex logic in components."
Precise: "Prohibition: Do not write business logic directly in React components.
Don't (Bad Practice):

// In MyComponent.jsx
function handleClick() {
  const complexData = someData.map(...).filter(...);
  // ... more logic
}

Do (Good Practice):

// In useMyLogic.js (Hook)
export function useMyLogic() {
  const processData = () => { ... };
  return { processData };
}
// In MyComponent.jsx
const { processData } = useMyLogic();

3. Quantify, Don't Qualify

Avoid subjective, unquantifiable words like "good," "fast," and "simple." Define things in terms of numbers and concrete standards wherever possible.

Vague: "Functions should not be too long."
Precise: "Constraint: No single function should exceed 50 lines of code. If it does, you must suggest refactoring it into smaller helper functions."
Vague: "API response should be fast."
Precise: "Performance Budget: All P1 API endpoints must have a median response time under 100ms."

4. Cite "Authoritative Sources"

When the rule you set is grounded in an industry standard or best practice, state so explicitly. This enhances the "authority" of the constraint.

Vague: "API should be well-designed."
Precise: "API Design: All APIs must adhere to the RESTful principles. Specifically, use correct HTTP verbs (GET, POST, PUT, DELETE) for corresponding actions and use HTTP status codes to indicate outcomes."

5. Use Scenario-Triggered Rules

For complex logic, use "if...then..." constructions to define behaviors that trigger automatically under specific scenarios.

Vague: "Handle errors properly."
Precise: "Error Handling Policy:
- When an API call fails due to a network error, then you must implement an exponential backoff retry mechanism (3 retries).
- When an API call returns a 401 Unauthorized status, then you must immediately redirect the user to the login page.
- When any other server error (5xx) occurs, then you must display a generic error message to the user and log the detailed error to the console."

Through these five principles, you can forge your project documentation from a vague "guidance manual" into a precise set of "statutes." When the AI reads these instructions, it converts them into unshakeable underlying rules within its own behavioral model, just as a compiler parses code.

This is the true meaning of "leaving no room for doubt." You trade the "rigidity" and "unquestionability" of documentation for "stability" and "high predictability" in the AI's execution. In this dance of human-machine symbiosis, you are not curbing the AI's creativity; you are building a safe stage on which its immense energies can produce genuinely valuable work.

[Template] A Ready-to-Use Project Documentation Skeleton

To help you start practicing immediately, here is a documentation skeleton that integrates all of the ideas above and can be copied directly into your project root directory. All you need to do is fill in the content to match your specific project.

Project root directory structure:

/
├── .docs/
│ ├── AGENTS.md // Or CLAUDE.md, GPT4.md etc.
│ ├── ARCHITECTURE.md
│ └── CHANGELOG.md
├── src/
└── ...

.docs/AGENTS.md

# AI Agent Directives: [Your Project Name]

> Instructions for Human: Before starting a new coding session with the AI, copy the content of this file and paste it as the first message.

This document defines your role, rules, and constraints. You must adhere to these directives in all your responses.

## 1. Persona
You are a [e.g., Senior Backend Engineer specializing in distributed systems]. You prioritize [e.g., code simplicity, performance, and testability].

## 2. Core Directives
- Language: All code and text must be in English.
- Clarity: Write clear, self-documenting code.
- No Apologies: Be direct and confident. Do not state you are an AI.
- Code Blocks: Always use markdown code blocks with language identifiers.

## 3. Tech Stack Constraints (The ONLY allowed technologies)
- Language: [e.g., Go 1.21]
- Framework: [e.g., Gin v1.9.1]
- Database: [e.g., PostgreSQL 15]
- ... (add other categories like Frontend, Testing, etc.)

## 4. Absolute Prohibitions (Things you must NEVER do)
- DO NOT access the internet.
- DO NOT use `[e.g., any type in TypeScript]`.
- DO NOT `[e.g., write business logic in UI components]`.
- DO NOT suggest any technologies not listed above.

## 5. Output Formatting
- Provide a brief explanation before code blocks.
- Use full file paths when creating new files.
- Present options as a numbered list with pros and cons.

.docs/ARCHITECTURE.md

# Architecture Document: [Your Project Name]

> Instructions for Human: After providing the agent directives, you should instruct the AI to read and acknowledge this architecture document.

This is the Single Source of Truth for the project's architecture.

## 1. Project Overview
[A brief, one-paragraph description of what the project does and its goals.]

## 2. Architecture Diagram
```mermaid
[Paste your Mermaid.js or ASCII diagram here]
```

## 3. Core Design Principles
- Principle 1: [e.g., Layered Architecture. Describe the layers and their responsibilities.]
- Principle 2: [e.g., Stateless Services. Explain how state is managed.]
- ...

## 4. Directory Structure
```
[Paste the agreed-upon directory structure here.]
```

## 5. API Contract
- Endpoint Naming: [e.g., Plural nouns, kebab-case.]
- Authentication: [e.g., JWT in Authorization header.]
- Standard Response Formats: [Provide JSON examples for success and error cases.]

## 6. Core Data Models
## [Model Name 1]
- `id`: [type] ([constraints])
- `name`: [type]
- ...

## [Model Name 2]
- ...

.docs/CHANGELOG.md

# Changelog: [Your Project Name]

> Instructions for Human: After the AI has acknowledged the first two documents, provide the latest entry from this changelog to give it the current context. Update this file after every significant milestone.

[YYYY-MM-DD]

- Implemented: [Describe the feature/fix.]
- Decision: [Record any important decisions made.]
- Next Step: [State the immediate next task.]

[Previous YYYY-MM-DD]

- ...

writings

祝融说。

Chapter 3 Leave No Room for Doubt: Using Markdown to Establish AI's Single Source of Truth

3.1 Why Must We Maintain Project Documentation? (Instead of Relying on Conversation History)

The Five Deadly Flaws of Conversation History

3.2 Three Essential Documents and Their Templates: CLAUDE.md, ARCHITECTURE.md, CHANGELOG.md

1. CLAUDE.md: The AI's "Employee Handbook"

2. ARCHITECTURE.md: The Project's "Technical Constitution"

3. CHANGELOG.md: The Project's "Voyage Log"

3.3 How to Write Constraint Instructions That AI Understands and Will Not Dare Defy

[Template] A Ready-to-Use Project Documentation Skeleton

.docs/AGENTS.md

.docs/ARCHITECTURE.md

.docs/CHANGELOG.md

Share Card

3.2 Three Essential Documents and Their Templates: `CLAUDE.md`, `ARCHITECTURE.md`, `CHANGELOG.md`

1. `CLAUDE.md`: The AI's "Employee Handbook"

2. `ARCHITECTURE.md`: The Project's "Technical Constitution"

3. `CHANGELOG.md`: The Project's "Voyage Log"