智能协作新范式：构建AI友好的文档体系与工作流

1
#!/bin/bash
2
echo "🔍 AI Session Starting - $(date)"
3

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

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

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

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

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

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

28
echo "✅ Session initialized. Ready to work."

1
## 单一任务原则
2

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

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

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

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

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

1
#!/bin/bash
2
echo "🏁 AI Session Ending - $(date)"
3

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

14
# 2. 更新功能清单
15
echo "✅ Updating feature list..."
16
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
17

18
# 3. 提交代码
19
echo "💾 Committing changes..."
20
git add .
21
git commit -m "feat(profile): implement user profile management
22
- Add profile form component
23
- Integrate profile API service
24
- Add form validation logic
25
- Add unit and E2E tests
26
Ref:#123"
27
git push origin feature/user-profile
28

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

1
#!/bin/bash
2
FEATURE_ID=$1
3

4
echo "🔍 Validating feature: $FEATURE_ID"
5

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

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

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

30
# 4. 更新状态
31
echo "✅ All validation passed for $FEATURE_ID"
32
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
33

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

1
## 决策原则
2

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

7
## 协作流程
8

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

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

21
## 示例场景
22

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

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

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