chill/chill_notes

Fork 0

Files

FNS Service 682e3e52df Update from Sync Service

2026-06-22 11:30:51 +08:00

12 KiB

Executable File

Raw Permalink Blame History

团队级 AI Coding 简明手册 v0.2

来源：系统设计研讨会分享 PPT（2026.06.18），版权归分享人所有归档日期：2026-06-20

一、AI 编程思想发展过程

阶段	特征	模式
原始阶段	基于本能的 AI 编程，手动复制代码或通过问答交互	半自动，有人值守
Rule 约束	经验规则显化（如 RIPER-5），通过持续对话输入需求	半自动
规格驱动	需求结构化表达，基于规格流转（如 OpenSpec），文件进文件出	全自动过渡
Loop Engineering	可反馈闭环：AI 根据验收规则自动循环 + 测试套件	全自动
Harness 驾驭工程	纳入工程治理体系，提供约束体系 + 外部接口	全自动，Plan 后无人值守

每一次思想的变更是对前者的重新表述而非推翻

二、AI 赋能软件开发实现地图

需求分析 → 需求文档/原型图 → 技术方案设计 → 代码框架+打样工程
    ↓            ↓                ↓                ↓
  人+AI        人+AI             人+AI            人+AI
    ↓            ↓                ↓                ↓
AI代码编写 → 单元测试/调试 → E2E测试 → Code Review → 提测部署
    ↓            ↓              ↓           ↓           ↓
  机           机+人           机+人        机+人        机+人

核心 Loop：研发自测阶段，AI 自治运行 全流程超级 Loop：从需求到部署的完整闭环

三、四大核心问题

01 需求衔接

如何编写 AI 能理解的需求？
使用什么格式？如何组织需求规格？
如何传递原型图？需求模版长什么样？

02 开发实现

如何让 AI 理解上下文且按要求执行？
如何调用外部工具？生成一致的代码？
如何多任务同步开发？

03 测试验收

AI 编程需要什么测试策略？
如何让 AI 操作浏览器？
如何管理测试用例？

04 Agent as Code

如何把和 AI 协作的文件在代码仓库中合理组织？
构建 AI 更友好的环境

四、需求规格编写

关键要素

模块切分（增量/存量）
字段清单
原型链接
业务规则

编写原则

先写业务背景，再切模块。一个模块 = 一个文档
分解为增量需求和存量需求：
- 增量需求 — 全新功能，需新建模块
- 存量修改 — 对已有功能做变更
字段定义需完整：类型、必填、默认值、描述、校验规则、UI展示、数据来源
业务规则条目化 + 正交分解，每条规则独立可测

Tips: BA 也应该工作在代码仓库中，让 AI 基于当前系统事实构建新需求

原型图设计

设计工具输出：Figma/Stitch URL 嵌入需求文档
HTML+CSS 输出：可交互原型提交到代码仓库
Design.md：约束 AI 生成的前端风格，确保与项目组件库一致

五、开发实现

让 AI 听话的三要素

要素	说明	示例
规则 Rules	约束 AI 行为边界	Java 代码风格、命名规范
规格 Specification	结构化需求，甚至用 DSL 描述	用户故事 + 验收标准
技能 Skill	打包提示词/脚本/模版扩展能力	Commit & Push Skill

构建 AI 上下文体系（详见下方重点章节）

让 AI 调用外部工具的三种方式

CLI Commands — 最直接，AI 生成命令并执行
MCP — 标准协议，统一接入数据库/API/文件系统
Skills — 脚本封装，触发词驱动

AI 编程工具选择

命令行类：Claude Code、Codex CLI、OpenCode
AI IDE：Cursor、Kiro、Trae
增强插件：Superpower、oh-my-opencode、oh-my-codex

SDD 框架对比

维度	BMAD	Spec Kit	OpenSpec	Kiro
定位	企业级 SDD 操作系统	工程化 Spec 工作流	轻量 Spec 层	IDE 原生 SDD
Spec 粒度	大（系统/模块级）	中（Feature级）	小（变更/Patch级）	中（Feature+行为）
自动验证	无	无	弱	强（内建）
适用场景	大型系统/多团队	新项目（0→1）	存量项目/快速迭代	小团队/高自动化

技术规格编写（DSL 驱动）

模块	标准	格式	约束
领域模型	PlantUML/Smart Domain	.puml	必须表达实体关系
数据库	SQL DDL/DBML	.sql	必须可执行
API	OpenAPI 3.x	.yaml/.json	必须定义 schema
时序图	PlantUML	.puml	必须反映真实调用链
专题设计	Markdown	.md	只写策略与规则

打样工程：让 AI 抄作业

原则：约定大于配置、编排逻辑和原子能力分离、操作者和被操作对象分离
简单 CRUD：Controller + Command → AppService → Repository → Response
复杂 CRUD：Controller + Command → AppService → DomainService → Repository → Response
复杂查询：Controller + Query → AppService → QueryPO → Response

多任务同步开发

使用 git worktree 同时把多个分支映射到不同文件夹：

git worktree add -b feature-payment ../feature-payment

六、⭐ 过程方案 vs 事实方案（重点）

核心理念

使用完整的文档来描述上下文和约束体系，区分过程方案和事实方案，减少维护成本。

文档分层体系

AGENTS.md          ← 宪法级约束
docs/
├── standards/     ← 标准规格（架构/命名/API/安全规范）
├── features/      ← 需求规格（产品/BA维护）
├── designs/       ← 设计规格（DB/表等 Source of Truth）  ⬅ 事实方案
├── plans/         ← 计划规格（每轮任务实现方案）          ⬅ 过程方案
└── others/        ← 架构决策、Release、测试用例等

过程方案（Plans）

定义：每一轮任务的实现方案、Tasking、工作状态。

特征：

临时性：每次创建新文件，用完即弃
不维护：细微修改不再更新旧文件
可追溯：保留历史决策轨迹，方便复盘
增量追加：追加: 每次创建一个新的文件

示例：

docs/plans/
├── plan-2026-06-01-user-auth.md      # 第1轮
├── plan-2026-06-05-user-auth-v2.md   # 第2轮迭代
├── plan-2026-06-10-payment-flow.md   # 新任务
└── plan-2026-06-15-order-module.md   # 新任务

为什么这样设计：

避免反复修改同一文件导致的 Git 冲突
保留完整决策轨迹，AI 和人都能回溯
AI 执行完可以"丢弃"，不污染长期文档
降低维护成本——过程方案不需要维护

在 Plan/Go 模式中的角色：

Plan 阶段产出 → 锁定上下文到 Plan 中
记录实现状态，让任务可以分批完成或重试
关闭所有开放性问题后再进入执行

事实方案（Designs / Standards / Features）

定义：反映系统当前真实状态的文档，是 Source of Truth。

特征：

长期有效：稳定的、持续维护的
最终态更新：变更: 每次以最终态更新
事实依据：作为下一次 Plan 的起点
必须一致：与实际代码/系统保持同步

示例：

docs/designs/
├── database-schema.md      # 当前数据库表结构（最终态）
├── api-endpoints.md        # 当前 API 定义（最终态）
└── architecture.md         # 当前架构图（最终态）

docs/standards/
├── coding-style.md         # 编码规范
└── security-guidelines.md  # 安全规范

docs/features/
├── user-management.md      # 用户管理需求（当前版本）
└── order-system.md         # 订单系统需求（当前版本）