Chapter 7: Documentation Evolution

In the Agent era, documentation transforms from static records into core assets that drive execution. BDD’s Given-When-Then structure serves as the bridge connecting human intent to Agent execution, while project-level specifications and architectural constraints form the “living contract” of human-Agent collaboration.

1 Re-examining the Agile Manifesto

The Agile Manifesto (2001) states:

Working software over comprehensive documentation

This is often misread as “no documentation needed.” But Agile’s true intent emphasizes value prioritization: if a document doesn’t directly help deliver working software, its priority should be lowered. Documentation is a means; software is the end.

However, in Agent-Oriented Software Engineering (AOSE), this value needs re-examination. When AI Agents become the primary executors, we discover: the form of documentation determines the quality of Agent execution. Vague documentation leads to Agent “hallucinations” and code that misses requirements; precise, structured, Agent-understandable documentation can greatly increase the probability of Agents getting it right the first time.

Thus, AOSE offers a new interpretation of the Agile Manifesto:

Agent-friendly expression rapidly builds executable software

Here, “Agent-friendly expression” is a requirement description form that AI can accurately understand—it is both an expression of human thought and machine-parseable execution instructions. It is no longer just “documentation,” but a core asset that directly drives software development.

2 The Triple Dilemma of Traditional Documentation

Before exploring the new paradigm, let’s examine why traditional documentation systems cannot sustain themselves in the AI era.

Static Nature and Lag: Documentation is Dead

BRDs, PRDs, and technical documents tend to ossify once finalized. In traditional development, deviation between documentation and code is the norm—teams modify code to respond to changes but forget to update documentation. Three months later, documented functionality bears little resemblance to reality. This “documentation is dead” phenomenon makes people prefer reading code.

In AOSE, this problem becomes severe: if Agents generate code based on outdated documentation, consequences will be disastrous.

Ambiguity: The Breeding Ground for AI Hallucinations

Natural language is inherently ambiguous. Descriptions like “user-friendly,” “smooth experience,” and “premium feel” have different interpretations in different minds. Human developers can clarify through communication, but when Agents face vague descriptions, they “hallucinate” based on training data, producing unpredictable deviations.

This “undefined state” is the root of hallucinations—Agents fill information gaps themselves, and these fillings often diverge from business expectations.

Execution Gap: Information Loss in Translation Chains

Traditional documentation cannot directly drive behavior. Business writes BRDs, product translates to PRDs, developers translate to code, testers translate to test cases. Each translation introduces information decay and errors.

In the AI era, we want Agents to directly understand requirements. But there is a huge gap between natural language documentation and executable code—Agents cannot determine what “improving user experience” specifically means.

3 BDD: The Bridge Connecting Human Requirements and AI Execution

In AOSE, BDD (Behavior-Driven Development) is no longer just a testing tool, but has evolved into a high-level requirements expression language for humans to “program” Agents.

Gherkin Syntax: Structured Expression of Requirements

BDD’s representative language form is Gherkin syntax. Through highly structured natural language (Given-When-Then), it transforms human business requirements into instructions that machines can parse, verify, and execute.

Case Comparison: Natural Language vs. BDD Precision

Traditional Natural Language (Ambiguous Requirements):

“As a premium member, if I buy something over 100 bucks, I should get a 10% discount at checkout.”

Problems: What about regular members? Is exactly 100 discounted? Is discount calculated before or after shipping? Are promotional items included?

BDD Language (Precise Requirements):

Feature: Shopping Cart Checkout Discount Rules

  Scenario: Premium members enjoy 10% discount on purchases over 100 yuan
    Given user "Zhang San" has membership level "VIP"
    And "Zhang San" has shopping cart total of "105.00" yuan
    And items are not promotional special-price items
    When "Zhang San" initiates "submit order" action
    Then the system's calculated final payable amount should be "94.50" yuan
    And the system's order status should update to "pending payment"

  Scenario: Regular members do not enjoy discount
    Given user "Li Si" has membership level "Regular Member"
    And "Li Si" has shopping cart total of "150.00" yuan
    When "Li Si" initiates "submit order" action
    Then the system's calculated final payable amount should be "150.00" yuan

In BDD, requirements are clearly anchored on “preconditions,” “trigger actions,” and “asserted results,” leaving no room for ambiguity.

BDD and LLM Prompt Isomorphism

BDD works efficiently in the AI era because it aligns perfectly with large language model cognition patterns:

Feeding BDD scripts directly to Agents, they can instantly understand what system logic they need to build. This structured requirements expression is the key to eliminating AI hallucinations.

4 The AI-Friendly Documentation Paradigm

In AOSE, traditional documentation (BRD/PRD/TRD) is reorganized into two types of AI-oriented specifications:

1. Requirements Specification: Humans describing to AI “what we want to achieve”
2. AI Agent Specifications: Humans stipulating to AI “how to work correctly”

Together they form the contract of human-machine collaboration—the former ensures Agents understand correct business objectives, the latter ensures Agents implement correctly.

Requirements Specification

Replaces: BRD (Business Requirements Document) + PRD (Product Requirements Document)

Core Question: What goals do we expect to achieve? In what scenarios? How should users perceive it? How is success measured?

Requirements specification uses BDD language to uniformly describe business goals and product features:

Feature: Enhance Paid Member Benefit Perception
  As a business leader
  I want to display a "Priority Processing" badge in the member center
  So as to enhance annual members' sense of exclusivity and renewal willingness

  Background:
    Given current annual member renewal rate is 62%
    And 35% of customer service inquiries are related to "priority processing benefits"

  Scenario: Annual member views badge
    Given user is logged in
    And user membership level is "annual member"
    When user visits "member center" page
    Then page should display gold "Priority Processing" badge
    And badge position should be next to username
    And badge color should be #FFD700

  Scenario: Regular member does not display badge
    Given user is logged in
    And user membership level is "regular member"
    When user visits "member center" page
    Then page should not display "Priority Processing" badge

Key Elements:

• Business background and value proposition (Feature description + Background)
• Functional scenarios and user experience (Scenario)
• Normal/boundary/exception scenario coverage
• Clear acceptance criteria (Then assertions)

The core value lies in eliminating ambiguity. Natural language descriptions are often full of implicit assumptions (“good user experience,” “appropriate display”), while BDD’s Given-When-Then structure forces requirement providers to anchor every requirement on specific conditions, actions, and results.

AI Agent Specifications

Replaces: TRD (Technical Requirements Document) + Development Specifications

Core Question: Within what boundaries does the Agent work? How to ensure quality meets standards?

AI Agent specifications define universally applicable working methods and quality boundaries. It has two interrelated levels:

Together they constitute the persistent knowledge base of technical requirements.

Level One: Project-Level Prompts

Positioning: Agent’s “onboarding manual” for entering the project

Typical Files:

• .cursorrules (Cursor IDE)
• CLAUDE.md (Claude Code)
• .ai-context.md (general)

Content Structure:

# Project Technical Requirements

## Technology Stack and Architecture
- Backend: Python FastAPI + SQLAlchemy
- Frontend: React + TypeScript + Tailwind
- Database: PostgreSQL 14+
- Cache: Redis Cluster

## Coding Standards
- All APIs must use Pydantic models for request/response validation
- Database queries must use parameterization—no string concatenation SQL
- Async functions must use `async`/`await`—no mixing thread pools

## Project Structure

src/ api/ # Route definitions—no business logic services/ # Core business logic models/ # SQLAlchemy models schemas/ # Pydantic models infrastructure/# Cache, queues, other infrastructure

## Special Constraints
- User table `users` `id` field uses snowflake algorithm, not auto-increment
- All amount calculations must use `Decimal` type—no float
- Legacy system `legacy_order` table is read-only—no writing

Value:

• Let Agents understand project technical context before receiving specific tasks
• Avoid Agents repeatedly asking basic questions
• Encode project-specific conventions as instructions Agents can follow

Level Two: Architecture Constraints

Positioning: Quality boundaries enforced through automated tools

Implementation Forms:

1. Lint Rules (code style and basic quality)

# .pylintrc / pyproject.toml
[tool.ruff]
select = ["E", "F", "I", "N", "W", "UP", "B", "C4", "SIM"]
ignore = ["E501"]

[tool.mypy]
strict = true
warn_return_any = true
disallow_untyped_defs = true

2. Architecture Guard Rules (complexity and dependency control)

# archunit.py - architecture test example
import archunit

class ArchitectureTest:
    """Ensure architecture constraints are not violated"""

    def test_api_should_not_access_repository_directly(self):
        """API layer must not directly access Repository—must go through Service layer"""
        archunit.assert_that("src.api").should_not_depend_on("src.repositories")

    def test_domain_should_not_depend_on_infrastructure(self):
        """Domain layer must not depend on infrastructure layer (Clean Architecture)"""
        archunit.assert_that("src.domain").should_not_depend_on("src.infrastructure")

    def test_cyclomatic_complexity_should_be_below_10(self):
        """Cyclomatic complexity exceeding 10 must be refactored"""
        archunit.assert_complexity().is_less_than(10)

3. Security and Compliance Scanning (mandatory boundaries)

# .semgrep.yml
rules:
  - id: no-raw-sql-in-api
    pattern-either:
      - pattern: requests.post(..., data=$X, ...)
    message: "API layer must not construct direct SQL—must use ORM"
    severity: ERROR

  - id: no-hardcoded-secrets
    pattern-regex: '(api_key|password|secret)\s*=\s*["\'][^"\']+["\']'
    message: "Hardcoded keys prohibited"
    severity: ERROR

Value:

• Automated gatekeeping: Agent-generated code must pass all constraint checks
• Prevent degradation: Architecture quality won’t deteriorate as Agents generate new code
• Constraint as quality: Transform abstract “high quality” into verifiable concrete rules

5 Chapter Summary

From the Agile Manifesto’s “working software over comprehensive documentation” to AOSE’s “Agent-friendly expression, rapidly building executable software,” the role of documentation has undergone fundamental transformation.

Core Transformation

Key Concepts

1. BDD is the requirements expression language: Given-When-Then structure perfectly maps LLM cognition patterns, eliminating ambiguity and preventing hallucinations

2. Documentation as contract: Requirements specification and AI Agent specifications form execution contracts between humans and machines

3. Documentation as code: Requirements documents stored in version control, evolving with code

4. Constraints as quality: Technical requirements encode quality into automatically verifiable rules

5. Working software remains the goal: Agent-friendly expression is the means; delivering value is the goal. Documentation comprehensiveness should match business risk and system complexity.

In the Agent era, excellent product managers are not those who write the most documentation, but those who can express the most precise requirements with the most concise structured language. This capability—transforming vague business requirements into unambiguous structures—will become the core skill of software engineering.