Best Practices advanced 6 min read

Writing Documentation That Both Humans and AI Understand

Hướng dẫn chi tiết về Writing Documentation That Both Humans and AI Understand trong Vibe Coding dành cho None.

You’ve been there. It’s 2 AM, you’re deep in a “Vibe Coding” session, and your AI assistant—the one you’ve come to rely on as a digital extension of your own brain—suddenly decides to hallucinate a complete library that doesn’t exist. Or worse, it refactors a mission-critical utility into a pile of “elegant” garbage because it didn’t understand the hidden constraints of your legacy database.

This is the Context Crisis. In the era of high-velocity, AI-assisted development, traditional documentation is no longer just a “nice-to-have” for onboarding new hires. It is the fuel for your AI’s reasoning engine. If your documentation is stale, vague, or purely narrative, you aren’t just slowing down humans; you are poisoning the well for your AI agents.

To truly master Vibe Coding, you must adopt a Dual-Readability Framework: writing documentation that acts as a cognitive bridge for humans while providing a high-density semantic map for Large Language Models (LLMs).

The Core Concept: The Sentient Codebase

In traditional software engineering, documentation was often treated as a post-mortem activity. You wrote code, and then you wrote about the code. In the Vibe Coding paradigm, documentation is pre-computation. It is the set of instructions and constraints that define the “vibe” or the architectural direction before a single line of logic is generated.

AI doesn’t “read” documentation the way we do. It tokenizes it, weights it, and uses it to narrow the probability space of what it should generate next. When your docs are optimized for both, you create what we call a Sentient Codebase—a repository where the intent is so clearly mapped that an AI can navigate it with 99% accuracy, and a human can audit it in seconds.

1. Semantic Density over Narrative Fluff

LLMs have finite context windows. Even with 128k or 1M token limits, the “Lost in the Middle” phenomenon is real. If your documentation is buried in 500 words of “We are excited to share our journey with this API,” you are wasting precious tokens.

Human view: Needs a story to understand the “Why.” AI view: Needs predicates, constraints, and schemas to understand the “What.”

The solution is to use Structured Markdown. Use H1s and H2s not just for visual hierarchy, but as semantic anchors. Use frontmatter (YAML blocks at the top of Markdown files) to provide metadata that an AI can parse as “The State of Truth.”

The Anatomy of an AI-Human Document

Let’s look at a practical example. Imagine you are documenting a “User Authentication Service.” A traditional doc might list the endpoints. A “Sentient” doc defines the logic flow and the “Forbidden Zone.”

The Practical Example: AUTH_GUIDELINES.md

---
service: UserAuth
version: 2.1.0
criticality: High
ai_instruction: "Never modify the JWT signing logic without explicit human approval."
---

# User Authentication Service

## Executive Intent (The Why)
We use a stateless JWT-based system to ensure our microservices can scale without a centralized session store. This solves our 2025 bottleneck where the Redis session store caused a 200ms latency spike.

## Logic Flow (The How)
```mermaid
sequenceDiagram
    participant User
    participant Gateway
    participant AuthService
    User->>Gateway: POST /login
    Gateway->>AuthService: Validate Credentials
    AuthService-->>Gateway: Return JWT + Refresh Token
    Gateway-->>User: Set-Cookie (HttpOnly)

Architectural Constraints (The Rules)

  1. Token Expiry: Access tokens MUST NOT exceed 15 minutes.
  2. Encryption: Use RS256 only. HS256 is deprecated and blocked in CI.
  3. Database: Always query the users_readonly replica for validation to preserve primary IOPS.

Common Hallucination Triggers (AI Safety)

  • Do not suggest using localStorage for tokens. We are strictly HttpOnly cookies.
  • Do not implement a “remember me” feature using persistent cookies without checking the privacy_compliance.md file.

### Why This Works

1. **The YAML Frontmatter:** This is a "System Prompt" extension. When an AI reads this file, it immediately sees the `ai_instruction` and `criticality`. It knows this isn't a file to play around with.
2. **Mermaid Diagrams:** Mermaid is the secret weapon of Vibe Coding. LLMs are surprisingly adept at parsing the text-based syntax of Mermaid diagrams. It provides a structured representation of logic that is much harder to misinterpret than a paragraph of English.
3. **Intent-First Narrative:** By explaining *why* we moved away from Redis, we give the AI the context it needs to avoid suggesting Redis-based solutions later.
4. **The "Hallucination Triggers" Section:** This is a proactive defense. You are explicitly telling the AI: "I know you like to suggest `localStorage`, but don't do it here."

---

### Advanced Patterns: ADRs and the Project Memory

If you want to move from "Advanced" to "Elite" in Vibe Coding, you must implement **Architecture Decision Records (ADRs)**. 

An ADR is a short file that captures a specific decision at a specific point in time. For humans, it’s a history lesson. For AI, it is **Long-Term Memory**. When an AI agent joins your workspace, it scans your `/docs/adr/` folder. It learns that on March 12th, you decided to use `Zod` for validation instead of `Joi`. 

Now, when you ask the AI to "add a new field to the user profile," it won't suggest a Joi schema. It knows the history. It respects the decision.

#### Sample ADR Format for AI Alignment:

```markdown
# ADR 004: Standardizing on Tailwind v4

## Status: Accepted
## Date: 2026-03-25

## Context
We are seeing performance bottlenecks with runtime CSS-in-JS. The team wants to move to a zero-runtime utility-first approach.

## Decision
We will use Tailwind CSS v4. All new components must use utility classes. No `.module.css` files are allowed.

## AI Implications
- When generating UI, always use Tailwind v4 syntax.
- If you see a `.scss` file, propose a refactor to Tailwind.
- Use the `@theme` block in `src/styles/global.css` for design tokens.

Best Practices for Writing “Sentient” Docs

To ensure your documentation remains actionable and accurate, follow these four pillars:

Pillar 1: The “Why” is for Humans, the “What” is for Machines

When writing a function description, don’t just say // This function calculates tax. The AI can see that from the code. Instead, write: // This function implements the 2026 EU Digital Services Tax (Rule 402). Do not use for non-EU regions. This gives the human the “Why” (legal compliance) and the AI the “Constraint” (EU regions only).

Pillar 2: Explicit Constraint Mapping

AI is inherently optimistic. It wants to give you a solution that works in a vacuum. You must provide the atmospheric pressure.

  • List forbidden libraries.
  • Specify exact versions for sensitive dependencies.
  • Define performance budgets (e.g., “This function must execute in under 50ms”).

Pillar 3: Use “AI-Friendly” Nomenclature

Avoid puns, metaphors, or culturally specific idioms in your documentation. If you call a cleanup script “The Janitor,” a human might get it, but an AI might look for a “Janitor” class or library. Call it RESOURCES_CLEANUP_SERVICE. Be literal.

Pillar 4: The README as a Manifest

Your root README.md should not be a “How to Install” guide. It should be a Project Manifest. It should contain:

  • The Tech Stack (exact versions).
  • The Project Structure (what lives where).
  • The “Vibe” (e.g., “We prefer functional programming and immutability”).
  • The Testing Philosophy.

Interactive Tip: The AI Documentation Audit

Don’t wait for your documentation to fail. Use your AI to audit your docs. Run this prompt against your documentation folder:

“Act as a senior software architect. Review these documentation files. Identify three areas where the instructions are ambiguous enough to cause an AI to hallucinate or make a sub-optimal architectural choice. Propose specific Markdown changes to add constraints.”

You will be shocked at how often the AI points out that you haven’t defined the “Error Handling Policy” or the “Logging Convention.”

Conclusion: The Future of the Codebase

In Vibe Coding, your codebase is a living conversation. Documentation is the vocabulary and grammar of that conversation. By writing for both humans and AI, you reduce the friction of development and ensure that as your project scales, your AI assistant stays “on vibe.”

The ultimate goal of documentation in 2026 isn’t just to explain what the code does; it’s to encode the wisdom behind the code so that the next generation of AI agents can build upon it without repeating the mistakes of the past. Stop writing “Docs” and start building the Cognitive Layer of your application.