以 Python Django 为例，探讨在 Claude Code、Trae 等智能编程工具中，编写结构化 Markdown 文档对 AI 协作的重要价值。

---

一、引言

随着 Claude Code、Trae、Cursor、GitHub Copilot Chat 等智能编程工具的普及，开发者与 AI 的协作方式正在发生根本性变化。过去我们写文档是给人看的，现在我们写文档——尤其是 Markdown 文档——更多是给 AI 看的。

这一变化并非简单的"读者"切换，而是影响整个开发效率与代码质量的关键环节。本文将以 Python Django 项目为例，说明为什么在智能编程工具时代，为 AI 编写高质量的 Markdown 文档至关重要。

---

二、Markdown 是 AI 最友好的"输入格式"

2.1 为什么是 Markdown，而不是 Word 或纯文本？

格式	AI 解析能力	结构化程度	可维护性	推荐度
Markdown	高	高	高	⭐⭐⭐⭐⭐
Word (docx)	低（需额外转换）	中	低	⭐
纯文本	中	低	中	⭐⭐
JSON/YAML	高	极高	中	⭐⭐⭐⭐

Markdown 兼具人类可读性和机器可解析性：

• 标题层级（#、##、###）让 AI 快速理解文档结构；
• 列表与表格让 AI 精准提取信息；
• 代码块（```python）让 AI 区分"描述"与"代码"；
• 链接与引用让 AI 理解上下文关联。

2.2 Claude Code / Trae 如何"阅读"你的 Markdown

以 Claude Code 为例，当你把一个 README.md 或 ARCHITECTURE.md 放在项目根目录时，AI 会在分析上下文时优先读取这些文件。Trae 同样会通过项目扫描机制索引 Markdown 文件作为"项目记忆"。

这意味着：Markdown 文档本质上是写给 AI 的"系统提示词（System Prompt）"的一部分。

---

三、Python Django 项目中的实战案例

3.1 场景描述

假设我们有一个 Django 项目，包含以下模块：

• 用户认证（基于 DRF 的 JWT）
• 商品管理（CRUD + 图片上传）
• 订单系统（含状态机）
• 数据统计（聚合查询）

如果没有任何 Markdown 文档，AI 只能通过逐个读取源码文件来理解项目，效率低下且容易遗漏约束。

3.2 没有文档时 AI 的典型表现

用户：帮我给订单加一个"退款中"的状态

AI：（扫描 models.py）发现 Order 模型有 status 字段，
    类型是 CharField，choices 里有 pending/paid/shipped/done。
    于是直接在 choices 里加了 'refunding', '退款中'。

结果：
- 没有更新状态机流转逻辑；
- 没有更新 admin 后台展示；
- 没有考虑"已发货"是否允许退款；
- 漏了信号处理与通知逻辑。

3.3 有文档时 AI 的表现

假设项目根目录有 docs/ORDER_STATE_MACHINE.md：

# 订单状态机

## 状态定义
- pending（待支付）
- paid（已支付）
- shipped（已发货）
- done（已完成）
- cancelled（已取消）

## 合法流转
- pending → paid / cancelled
- paid → shipped / cancelled
- shipped → done
- done → （终态）

## 退款规则
- 仅 paid 与 shipped 状态可发起退款
- 退款需新增 refunding 状态，流转到 refunded 或 rejected

此时 AI 会：

1. 识别到现有状态机文档；
2. 在 choices 中新增 refunding、refunded、rejected；
3. 更新合法流转逻辑；
4. 提示你同步更新 admin 配置与通知信号；
5. 主动询问是否需要在 ORDER_STATE_MACHINE.md 中补充新状态。

这就是 Markdown 文档的价值：把"项目约定"变成 AI 能直接消费的上下文。

---

四、给 AI 写 Markdown 的核心原则

4.1 结构清晰，层级分明

# 模块名称
## 业务背景
## 数据模型
## 接口列表
## 业务规则
## 注意事项

避免把所有内容堆在一段里，AI 会"读晕"。

4.2 用代码块承载"事实"

描述接口、模型、配置时，优先用代码块而不是自然语言：

## 用户模型

​```python
class User(AbstractUser):
    phone = models.CharField(max_length=11, unique=True)
    nickname = models.CharField(max_length=32, blank=True)
​```

4.3 用表格表达"约束"

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| phone | string | 是 | 11 位手机号 |
| nickname | string | 否 | 最长 32 字符 |

4.4 明确"禁忌"与"约定"

AI 最容易踩的坑是"自由发挥"。明确写出禁止事项：

## 编码约定
- 禁止在 view 中直接写 ORM 查询，必须走 service 层
- 所有时间字段使用 UTC 存储，展示时转 Asia/Shanghai
- 不允许使用 ForeignKey 的 on_delete=CASCADE，统一 SET_NULL

4.5 保持文档与代码同步

过时的文档比没有文档更危险。建议：

• 在 PR 模板中加入"是否需要更新 docs/"勾选项；
• 用 mkdocs 或 docusaurus 渲染文档站点，倒逼维护。

---

五、推荐的 Markdown 文件组织

一个 Django 项目的推荐文档结构：

project/
├── README.md                  # 项目总览、快速启动
├── ARCHITECTURE.md            # 架构图、模块依赖
├── docs/
│   ├── CONTRIBUTING.md        # 开发规范、提交约定
│   ├── API.md                 # 接口文档
│   ├── DATA_MODEL.md          # 数据模型说明
│   ├── BUSINESS_RULES.md      # 业务规则汇总
│   ├── DEPLOYMENT.md          # 部署流程
│   └── modules/
│       ├── ORDER_STATE_MACHINE.md
│       ├── AUTH_FLOW.md
│       └── STATISTICS_AGGREGATION.md
└── ...

---

六、Claude Code 与 Trae 的差异化建议

6.1 Claude Code

• 强项：长上下文理解，适合阅读整篇 ARCHITECTURE.md 后做全局重构；
• 建议：在 CLAUDE.md（Claude Code 专用记忆文件）中写入项目级约定，如"本仓库使用 Django 4.2 + DRF + Celery"；
• 技巧：把"不要做什么"写在最前面，Claude 对否定指令的遵守度较高。

6.2 Trae

• 强项：项目级记忆与多文件关联，适合在 IDE 内持续协作；
• 建议：利用 Trae 的 project_memory.md 机制沉淀项目规则；
• 技巧：把高频修改的模块文档放在 docs/modules/ 下，Trae 会按需索引。

6.3 通用建议

无论使用哪种工具，以下三点都适用：

1. 文档要"写给未来的 AI 看"——假设下一个接手的协作者是失忆的 AI；
2. 用"约束 > 描述 > 示例"的顺序书写——AI 对约束最敏感；
3. 定期复盘 AI 的输出——如果 AI 频繁违反某条规则，说明该规则在文档中表达不够清晰。

---

七、一个完整的 Django 模块文档示例

下面是一个 docs/modules/ORDER_STATE_MACHINE.md 的完整示例：

# 订单状态机

## 1. 背景

订单是本系统的核心领域对象，状态流转涉及支付、库存、通知等多个模块。
本文件定义订单状态的合法流转路径，所有涉及订单状态变更的代码必须遵循本文件。

## 2. 状态定义

| 状态码 | 中文名 | 是否终态 | 说明 |
|--------|--------|---------|------|
| pending | 待支付 | 否 | 用户下单后默认状态 |
| paid | 已支付 | 否 | 支付回调成功后进入 |
| shipped | 已发货 | 否 | 商家发货后进入 |
| done | 已完成 | 是 | 用户确认收货或自动超时 |
| cancelled | 已取消 | 是 | 用户主动取消或超时未支付 |
| refunding | 退款中 | 否 | 用户发起退款申请 |
| refunded | 已退款 | 是 | 退款成功 |
| rejected | 退款驳回 | 是 | 退款申请被驳回 |

## 3. 合法流转

​```text
pending → paid / cancelled
paid → shipped / refunding / cancelled
shipped → done / refunding
refunding → refunded / rejected
​```

## 4. 业务规则

- 仅 `paid` 与 `shipped` 状态可发起退款；
- `pending` 状态超过 30 分钟自动流转到 `cancelled`；
- `shipped` 状态超过 7 天自动流转到 `done`；
- 状态变更必须通过 `OrderService.transition(order, target_status)` 方法，
  禁止直接 `order.status = 'xxx'; order.save()`。

## 5. 相关代码

- 模型：`orders/models.py::Order`
- 服务：`orders/services.py::OrderService`
- 信号：`orders/signals.py`
- 定时任务：`orders/tasks.py::auto_cancel_expired_orders`

## 6. 禁忌

- 禁止在视图层直接修改 `order.status`；
- 禁止跳过 `transition` 方法的校验逻辑；
- 禁止新增状态而不更新本文件。

---

八、结语

在 Claude Code、Trae 等智能编程工具日益强大的今天，写文档这件事正在从"负担"变成"杠杆"。

一份结构清晰、约束明确的 Markdown 文档，相当于给 AI 配备了一份"项目说明书"：

• 它让 AI 的回答从"猜测"变成"遵循"；
• 它让 AI 的代码从"能跑"变成"合规"；
• 它让你的团队从"口口相传"变成"文档即契约"。

给 AI 写 Markdown，本质上是给未来的自己减负。 越早把项目约定沉淀成文档，AI 协作的收益就越早到来。

---

本文由作者结合 Claude Code 与 Trae 实际使用经验整理，欢迎在实践中迭代完善。