Back to Insights

Insight Detail

practice2026-04-04

AI Agent 自我文档化实践报告

AI Agent 自我文档化实践报告

日期: 2026-04-04
背景: 在 innate-websites 项目中实现自动化文档维护机制

1. 问题背景

1.1 观察到的现象

在开发过程中，发现 AI Agent 能够自动完成以下行为：

当完成 Task 4 和 Task 5 后，AI Agent 自动更新了 docs/tasks/workflow.md，将任务标记为完成状态并添加了详细的完成摘要。

这引发了一个问题：为什么 AI 会自动更新文档？这是使用了某种 Skill 吗？

1.2 根本原因

经过分析，发现自动更新文档的行为源于项目 AGENTS.md 中的一条规定：

If you modified any files/styles/structures/configurations/workflows/... 
mentioned in `AGENTS.md` files, you MUST update the corresponding 
`AGENTS.md` files to keep them up-to-date.

这意味着：

  • AI 读取了项目规范
  • 识别出文档需要更新的场景
  • 自动执行了更新操作

2. 解决方案：WriteAgent Skill

基于以上观察，我们设计了一个专门的 WriteAgent Skill，用于规范和自动化 AI Agent 的文档维护行为。

2.1 Skill 定位

名称: write-agent
用途: AI Agent 自我文档化
目标: 确保代码与文档始终保持同步
位置: .trae/skills/write-agent/SKILL.md

2.2 核心设计原则

原则说明
及时更新将文档更新视为任务的一部分，不延迟到"后面再补"
精确描述准确描述实现的内容，更新具体的文件路径和代码示例
保持结构遵循现有文档的格式和风格，使用一致的标题层级
版本追踪记录重要的变更历史，标记已完成的任务

3. 实现细节

3.1 触发条件（何时更新）

WriteAgent Skill 定义了 5 种必须更新文档的场景：

  1. 修改了 AGENTS.md 中提到的文件/结构/配置

    • 添加了新的目录结构
    • 修改了配置文件
    • 更改了代码模式或约定

  2. 完成了任务或里程碑

    • Task 状态变更（进行中 → 完成）
    • 添加了新的功能模块
    • 修复了问题或 bug

  3. 创建了新的组件/模块/功能

    • 新的 UI 组件
    • 新的 API 端点
    • 新的工具函数

  4. 修改了架构或设计决策

    • 技术栈变更
    • 架构模式调整
    • 依赖关系变化

  5. 发现了文档中的过时信息

    • 代码与文档描述不符
    • 链接失效
    • 示例代码过时

3.2 更新模板（如何更新）

模板 1: 任务完成更新

## Task X: 任务标题 ✅

**状态**: 已完成

**完成内容**:
1. [x] 功能点 A
2. [x] 功能点 B
3. [x] 功能点 C

**实现细节**:
- 关键文件: `path/to/file.ts`
- 主要变更: 描述具体修改
- 技术方案: 简要说明实现方式

**验证方式**:
```bash
# 测试命令或验证步骤

相关提交: commit-hash (可选)


#### 模板 2: AGENTS.md 架构更新

```markdown
## Architecture

### 新增模块: ModuleName

project/ ├── new-module/ │ ├── components/ # 新增组件 │ ├── hooks/ # 新增 hooks │ └── utils/ # 工具函数


**功能**: 简要描述模块用途
**依赖**: 列出关键依赖
**入口**: `path/to/index.ts`

模板 3: 组件文档更新

### ComponentName

**用途**: 组件功能描述

**Props**:
| 属性 | 类型 | 必填 | 说明 |
|------|------|------|------|
| prop1 | string | 是 | 说明 |
| prop2 | number | 否 | 说明，默认: 0 |

**使用示例**:
```tsx
<ComponentName prop1="value" prop2={42} />

位置: packages/ui/src/components/component-name.tsx


### 3.3 自动化规则

WriteAgent Skill 定义了 4 条自动化规则：

规则 1: Task 状态同步 当: 用户说"完成 Task X" 或 "Task X 已完成" 做: 自动将对应文档中的 Task X 标记为 ✅，并添加完成摘要

规则 2: 文件创建同步 当: 在特定目录创建新文件 做: 检查 AGENTS.md 是否需要更新目录结构说明

规则 3: 配置变更同步 当: 修改配置文件 (如 next.config.mjs, tsconfig.json) 做: 更新 AGENTS.md 中的配置说明部分

规则 4: 依赖变更同步 当: 添加/删除/更新 npm 依赖 做: 更新文档中的依赖列表和版本说明


---

## 4. 实践收获

### 4.1 显式优于隐式

**收获**: 将"自动更新文档"的行为从隐式规则变为显式 Skill

| 方式 | 特点 | 问题 |
|------|------|------|
| **隐式** | AI 自己决定何时更新 | 不一致、不可预测 |
| **显式** | 明确定义触发条件和更新模板 | 可预期、可维护 |

### 4.2 文档即代码

**收获**: 将文档维护纳入开发流程，像对待代码一样对待文档

- 版本控制：文档变更纳入 git 管理
- 自动化：AI 辅助减少手动维护工作量
- 一致性：统一的格式和风格

### 4.3 上下文传承

**收获**: 通过 AGENTS.md + Skill 的组合，实现项目知识的传承

项目知识层级: ├── AGENTS.md # 项目特定的规则和需求 ├── .trae/skills/ # 可复用的 Skill 定义 │ └── write-agent/ # 文档维护 Skill └── docs/ # 实际的项目文档


### 4.4 人机协作新模式

**收获**: AI 不仅是代码生成工具，更是文档维护的协作者

传统模式：

开发 → 编码 → （遗忘文档）→ 代码与文档不同步


新模式：

开发 → 编码 → AI 自动提醒/更新文档 → 代码与文档同步


---

## 5. 最佳实践建议

### 5.1 项目初始化时

1. **创建 AGENTS.md**
   - 定义项目架构
   - 明确编码规范
   - 添加文档更新规则

2. **创建 WriteAgent Skill**
   - 定义文档更新模板
   - 明确触发条件
   - 建立检查清单

### 5.2 日常开发中

1. **使用状态标记**
   ```markdown
   ## Task Name ⏳  // 待开始
   ## Task Name 🔄  // 进行中
   ## Task Name ✅  // 已完成
   ## Task Name ❌  // 已取消/阻塞

  1. 添加时间戳

    **最后更新**: 2026-04-04
**完成时间**: 2026-04-04

  2. 保留变更历史

    ### 变更历史
- 2026-04-04: 初始实现
- 2026-04-03: 修复 bug #123
- 2026-04-02: 添加新功能 X

5.3 代码审查时

检查清单：

  • 代码变更是否伴随文档更新？
  • 新组件是否有文档说明？
  • API 变更是否更新了接口文档？
  • 架构变更是否更新了 AGENTS.md？

6. 实际应用案例

案例：Task 4 & 5 完成过程

场景: 修复 GitHub Token 问题并完成 fetch project support

AI 行为:

  1. 识别出这是 workflow.md 中定义的 Task 4 和 Task 5
  2. 完成任务后，自动更新 workflow.md
  3. 按照模板添加完成摘要：
    • 任务状态标记为 ✅
    • 列出完成的功能点
    • 添加验证方式
    • 记录运行结果

效果:

  • 无需人工干预，文档自动同步
  • 其他开发者可以立即看到最新进度
  • 历史记录完整可追溯

7. 未来展望

7.1 可能的扩展

  1. 自动生成变更日志

    • 基于 git commit 生成 CHANGELOG
    • 自动分类：Features / Bug Fixes / Breaking Changes

  2. 智能文档检查

    • 检测代码与文档的不一致
    • 自动提醒需要更新的文档

  3. 多语言文档同步

    • 自动翻译文档到多种语言
    • 保持各语言版本同步

7.2 推广建议

将 WriteAgent Skill 应用于：

  • 开源项目维护
  • 团队协作开发
  • 个人项目管理
  • API 文档维护

8. 参考资源

  • Skill 定义: .trae/skills/write-agent/SKILL.md
  • 项目 AGENTS.md: AGENTS.md
  • 任务文档示例: docs/tasks/workflow.md
  • 相关 Skill:
    • claude-frontend
    • codex-frontend
    • glm-frontend
    • kimi-frontend

总结

通过创建 WriteAgent Skill，我们将 AI Agent 的文档维护行为从隐式变为显式，实现了：

  1. 标准化 - 统一的文档更新规范
  2. 自动化 - 减少手动维护工作量
  3. 一致性 - 代码与文档始终保持同步
  4. 可追溯 - 完整的变更历史记录

这是一种新的人机协作模式，AI 不再是单纯的代码生成工具，而是成为项目文档的主动维护者。