Derick
2959 words
15 minutes
智能协作新范式：构建AI友好的文档体系与工作流
2025-10-15
ArchitectureDesign
AIAgent
AI

摘要：当AI需要跨越多个会话完成复杂任务时，成功的秘诀不在于模型能力，而在于精心设计的文档体系和工作流程。本文揭示如何通过标准化的文档结构、上下文传递机制和增量式任务管理，让AI代理在长期项目中保持连贯性和效率。

一、问题起源：AI的”记忆断层”困境#

在上一篇文章中，我们讨论了如何与AI协作，通过文档提升AI工程的记忆，这篇文章我们继续深化内容。

尽管现代AI模型具备强大的单次会话能力，但当任务跨越数小时甚至数天时，它们会在新的上下文窗口中”失忆”。即使是最新的AI大模型，在多次会话后仍会失败，主要表现为两种模式：

  1. 过度尝试：试图一次性完成整个应用，导致上下文耗尽，留下半成品
  2. 提前完成：看到部分功能已实现，就错误地宣告项目完成
graph TD
    A[初始提示] --> B{AI行为模式}
    B -->|过度尝试| C[一次性实现太多功能]
    B -->|提前完成| D[部分功能即宣告完成]
    C --> E[上下文耗尽，留下半成品]
    D --> F[功能不完整，质量低下]
    E --> G[后续会话无法有效继续]
    F --> G

二、解决方案框架：四层文档体系#

成功的AI协作始于文档体系的设计。我们需要一个既服务人类又服务AI的结构化知识库。以下是经过验证的四层架构：

项目根目录/
├── 00-AI-Initialization/           # 初始化层：为AI设置基础环境
│   ├── project-vision.md           # 项目愿景和范围
│   ├── feature-list.json           # 功能清单（关键！）
│   ├── init-environment.sh         # 环境初始化脚本
│   └── ai-role-definition.md       # AI角色和权限定义
├── 01-Standards/                   # 标准层：约束和规范
│   ├── naming-conventions.md       # 命名规范
│   ├── directory-structure.md      # 目录结构规范
│   ├── coding-standards.md         # 代码质量标准
│   └── testing-requirements.md     # 测试要求
├── 02-Implementation/              # 实现层：具体指南
│   ├── module-templates/           # 模块开发模板
│   ├── component-library-guide.md  # 组件库使用指南
│   ├── api-integration-guide.md    # API集成指南
│   └── incremental-development.md  # 增量开发指南
└── 03-Validation/                  # 验证层：质量保障
    ├── code-review-checklist.md    # 代码审查清单
    ├── testing-strategy.md         # 测试策略
    ├── progress-tracking.md        # 进度跟踪规范
    └── acceptance-criteria.md      # 验收标准

核心文件详解：feature-list.json#

这是解决”记忆断层”问题的关键。初始化代理会生成一个结构化的功能清单，防止AI随意修改或过早宣告完成。

{
  "project": "Web Application",
  "version": "1.0.0",
  "features": [
    {
      "id": "feature-001",
      "category": "functional",
      "priority": 1,
      "description": "User login functionality",
      "steps": [
        "Display login form with username and password fields",
        "Validate input format on client side",
        "Submit credentials to authentication API",
        "Handle successful authentication (redirect to dashboard)",
        "Handle failed authentication (display error message)",
        "Implement remember me functionality"
      ],
      "passes": false,
      "last_tested": "2024-11-29",
      "test_evidence": ""
    },
    {
      "id": "feature-002",
      "category": "functional",
      "priority": 2,
      "description": "User profile management",
      "steps": [
        "Fetch user profile data from API",
        "Display profile information in editable form",
        "Validate form inputs",
        "Submit profile updates to API",
        "Display success/failure notifications"
      ],
      "passes": false,
      "last_tested": "",
      "test_evidence": ""
    }
  ]
}

关键设计原则：

  • 使用JSON格式（AI不易意外修改结构）
  • 包含详细步骤（防止模糊理解）
  • 明确的通过/失败状态（防止过早宣告完成）
  • 优先级排序（指导任务选择）

三、AI工作流：三阶段任务循环#

通过标准化的工作流程，让AI在每次会话中都能高效工作。这个流程分为三个阶段：准备、执行、交接。

flowchart LR
    A[准备阶段] --> B[执行阶段]
    B --> C[交接阶段]
    C -->|下一次会话| A

    subgraph 准备阶段
        A1[读取进度文件]
        A2[查看git历史]
        A3[运行基础测试]
        A4[选择最高优先级任务]
    end

    subgraph 执行阶段
        B1[实现单一功能]
        B2[编写单元测试]
        B3[端到端验证]
        B4[代码质量检查]
    end

    subgraph 交接阶段
        C1[更新进度文件]
        C2[提交代码变更]
        C3[记录测试结果]
        C4[准备下一任务]
    end

1. 准备阶段：快速理解上下文#

每次会话开始时，AI需要快速理解当前状态。这通过标准化的初始化脚本实现：

#!/bin/bash
# scripts/ai-session-start.sh

echo "🔍 AI Session Starting - $(date)"

# 1. 显示当前目录
echo "📍 Current directory:"
pwd

# 2. 读取进度文件
echo "📖 Reading progress file..."
cat 00-AI-Initialization/claude-progress.txt

# 3. 查看git历史
echo "📈 Recent git commits:"
git log --oneline -5

# 4. 读取功能清单
echo "📋 Reading feature list..."
jq '.features[] | select(.passes == false) | .priority, .description' 00-AI-Initialization/feature-list.json

# 5. 启动开发环境
echo "🚀 Starting development environment..."
./00-AI-Initialization/init-environment.sh

# 6. 运行基础测试
echo "🧪 Running basic sanity tests..."
npm run test:basic

echo "✅ Session initialized. Ready to work."

AI标准开场白：

[Assistant] I'll start by getting my bearings and understanding the current state of the project.

[Tool Use] <bash - ./scripts/ai-session-start.sh>

[Assistant] Based on the initialization script output, I can see:
- Current progress: User authentication module 80% complete
- Last commit: "fix(auth): handle token expiration edge cases"
- Pending features:
  1. User profile management (priority: 2)
  2. Password reset functionality (priority: 3)
- Basic tests are passing

I'll focus on implementing the user profile management feature as it's the highest priority pending task.

2. 执行阶段：增量式进展#

AI被明确指示一次只处理一个功能，并通过严格的验证确保质量：

# 02-Implementation/incremental-development.md

## 单一任务原则

**AI必须严格遵守**：
1. 每次会话只处理一个功能特性
2. 优先选择feature-list.json中优先级最高的未完成功能
3. 实现必须通过所有验证步骤才能标记为完成

## 验证步骤（必须全部通过）

### 1. 代码质量验证
- [ ] 通过lint检查（无警告）
- [ ] 通过类型检查（无错误）
- [ ] 代码覆盖率 ≥ 80%
- [ ] 无安全漏洞（npm audit clean）

### 2. 功能验证
- [ ] 单元测试全部通过
- [ ] 集成测试全部通过
- [ ] 端到端测试通过（使用Puppeteer/Cypress）
- [ ] 跨浏览器测试通过（Chrome, Firefox, Safari）

### 3. 人工验证准备
- [ ] 更新文档说明
- [ ] 添加使用示例
- [ ] 准备演示脚本

3. 交接阶段：为下一任务铺路#

会话结束时，AI必须留下清晰的工件供下一代理使用：

#!/bin/bash
# scripts/ai-session-end.sh

echo "🏁 AI Session Ending - $(date)"

# 1. 更新进度文件
echo "📝 Updating progress file..."
cat <<EOL >> 00-AI-Initialization/claude-progress.txt
$(date): Completed feature-002 (User profile management)
- Implemented profile form component
- Added API integration for profile updates
- Added validation logic for form inputs
- All tests passing (coverage: 85%)
EOL

# 2. 更新功能清单
echo "✅ Updating feature list..."
jq '.features[] |= if .id == "feature-002" then .passes = true | .last_tested = "'$(date)'" | .test_evidence = "All unit and E2E tests passed" else . end' 00-AI-Initialization/feature-list.json > temp.json && mv temp.json 00-AI-Initialization/feature-list.json

# 3. 提交代码
echo "💾 Committing changes..."
git add .
git commit -m "feat(profile): implement user profile management
- Add profile form component
- Integrate profile API service
- Add form validation logic
- Add unit and E2E tests
Ref:#123"
git push origin feature/user-profile

echo "✨ Session completed successfully. Ready for next task."

四、验收机制：质量门禁与自动验证#

防止AI标记未完成功能为”完成”的关键是建立严格的验收机制。

flowchart TB
    A[AI标记功能为完成] --> B{自动验证}
    B -->|单元测试| C[运行测试套件]
    B -->|代码质量| D[静态代码分析]
    B -->|功能验证| E[端到端测试]
    C --> F{通过?}
    D --> G{通过?}
    E --> H{通过?}
    F -->|否| I[拒绝验收]
    G -->|否| I
    H -->|否| I
    F -->|是| J
    G -->|是| J
    H -->|是| J
    J[更新feature-list.json] --> K[通知人类审核]
    I --> L[AI修复问题]

自动化验收脚本#

#!/bin/bash
# scripts/feature-validation.sh

FEATURE_ID=$1

echo "🔍 Validating feature: $FEATURE_ID"

# 1. 运行单元测试
echo "🧪 Running unit tests..."
npm run test:unit -- --feature=$FEATURE_ID
if [ $? -ne 0 ]; then
    echo "❌ Unit tests failed for $FEATURE_ID"
    exit 1
fi

# 2. 代码质量检查
echo "🧹 Code quality check..."
eslint src/features/$FEATURE_ID --max-warnings=0
if [ $? -ne 0 ]; then
    echo "❌ Code quality issues found for $FEATURE_ID"
    exit 1
fi

# 3. 端到端测试
echo "🌐 End-to-end testing..."
npm run test:e2e -- --spec=features/$FEATURE_ID.feature
if [ $? -ne 0 ]; then
    echo "❌ E2E tests failed for $FEATURE_ID"
    exit 1
fi

# 4. 更新状态
echo "✅ All validation passed for $FEATURE_ID"
jq ".features[] |= if .id == \\"$FEATURE_ID\\" then .passes = true | .last_tested = \\"$(date)\\" else . end" 00-AI-Initialization/feature-list.json > temp.json && mv temp.json 00-AI-Initialization/feature-list.json

echo "🎉 Feature $FEATURE_ID successfully validated and marked as complete."

五、进阶实践：人类-AI协作协议#

最强大的系统不是纯AI或纯人类，而是两者的协同。我们需要明确的协作协议：

责任矩阵#

任务类型AI责任人类责任交接点
功能实现生成基础代码、测试、文档代码审查、业务逻辑验证PR审查
架构决策提供选项和分析最终决策、战略规划架构评审会
问题诊断日志分析、可能原因根本原因、业务影响问题报告
质量保障自动化测试、代码检查用户体验、边缘情况验收测试
知识管理文档生成、更新知识审核、经验总结文档评审

冲突解决机制#

当AI和人类意见不一致时，遵循以下原则：

# 01-Standards/conflict-resolution.md

## 决策原则

1. **安全第一**：涉及安全、隐私、合规的问题，人类决策优先
2. **业务价值优先**：业务影响大的决策，人类主导
3. **技术债务最小化**：避免短期便利导致长期维护成本

## 协作流程

1. **AI提出异议时**：
   - 必须提供具体问题分析
   - 提供2-3个替代方案
   - 说明每个方案的优缺点
   - 推荐最佳方案及理由

2. **人类决策时**：
   - 考虑业务优先级
   - 评估长期维护成本
   - 确保架构一致性
   - 记录决策理由供AI学习

## 示例场景

**人类要求**：跳过单元测试快速实现功能
**AI响应**：
"⚠️ 检测到技术债务风险：跳过单元测试可能导致：
- 未来修改时引入回归bug
- 难以理解代码意图
- 增加维护成本

**替代方案**：
1. **快速测试方案**：生成基础测试用例（2小时），覆盖80%核心场景
2. **分阶段方案**：先实现功能，2天内补全测试
3. **TDD方案**：先写测试，再实现（推荐，但需要4小时）

**推荐**：选择方案2，平衡速度和质量。"

六、实施路线图：从零开始#

阶段1：基础设置#

  • 创建四层文档结构
  • 配置自动化脚本
  • 定义核心功能清单
  • 设置CI/CD流水线

阶段2：第一个功能迭代#

  • AI实现一个简单功能
  • 人类审查和调整流程
  • 优化文档和脚本
  • 建立反馈循环

阶段3：流程优化（持续迭代）#

  • 分析失败模式
  • 增强自动化验证
  • 扩展功能覆盖
  • 培训团队协作
gantt
    title AI协作项目实施路线图
    dateFormat  YYYY-MM-DD
    section 基础设置
    文档结构创建       :done,    des1, 2025-01-01, 1d
    自动化脚本配置      :done,    des2, 2025-01-02, 1d
    CI/CD流水线设置     :active,  des3, 2025-01-03, 2d

    section 第一迭代
    核心功能定义       :         des4, 2025-01-05, 1d
    AI实现与验证       :         des5, 2025-01-06, 2d
    人类审查与优化      :         des6, 2025-01-08, 1d

    section 优化扩展
    流程改进          :         des7, 2025-01-10, 3d
    团队培训          :         des8, 2025-01-13, 2d
    全面推广          :         des9, 2025-01-15, 5d

七、结语：AI协作的未来#

此刻我内心在想：AI的终极价值不在于它能做什么，而在于它如何被工程化地使用。当我们将”AI的尽头是软件工程”这一理念付诸实践时，我们不仅提升了开发效率，也重新定义了人机协作的边界。

通过精心设计的文档体系、标准化的工作流程和严格的验收机制，我们让AI代理在长期项目中保持连贯性和效率。这不是关于取代人类开发者，而是关于放大人类创造力——让AI处理重复性工作，让人类专注于创新和战略思考。

智能协作新范式：构建AI友好的文档体系与工作流
https://blog.ithuo.net/posts/product-ai-engineering-collaboration/
Author
Derick
Published at
2025-10-15
打造预测市场的“赛博终端”：Polymarket 实时数据监控系统架构设计
让AIAgent交替工作：构建跨会话的高效开发流程