Appearance
新项目案例：从零散材料到可开发方案
这个案例没有保留客户名称、设备型号和完整协议。保留下来的是推进方法：最初有哪些材料，AI 在哪里把“常见做法”误当成“项目事实”，人工怎样纠正，以及设计和任务怎样逐步变得可实现、可验证。
案例定位： 这是一条适用于“新项目/新子系统”的 Discovery + Design 路线，不是日常 MicroPatch 的默认流程。已有明确需求的小改不需要照着本页从头走一遍。
本案例已记录阶段
| 阶段 | 覆盖情况 | 说明 |
|---|---|---|
| 需求 | 已记录 | 原始材料、Facts/Decisions、Frontier 和范围缺口 |
| 总体设计 | 部分记录 | 保留模块、流程、通信和数据方向，不补造完整架构文档 |
| 详细设计 | 部分记录 | 状态机、界面结构、通信数据有专题记录 |
| 开发 | 任务拆分记录 | 只记录任务结构，不等同于完整代码过程 |
| 测试 | 风险记录 | 记录最低验收和未验证风险 |
| 交付 | 未完整覆盖 | 不写成假完整交付案例 |
| 沉淀 | 已记录 | 需求发现、状态机、通信证据、验收边界 |
建议阅读时重点看：
text
Fact
→ Decision
→ Design
→ Task
→ Evidence而不是把案例中的具体状态名、异常后果或模块划分照搬到另一个项目。
1. 最初拿到的材料
项目开始时没有一份完整需求，只有零散输入：
| 材料 | Agent 可以确认 | 仍可能需要决策 |
|---|---|---|
| 客户技术要求 | 已写明的功能、接口、性能要求 | 异常后果、优先级、验收边界 |
| 旧软件截图 | 页面区域、高频信息、历史交互 | 新版是否继续保留这些交互 |
| 设备清单 | 设备类型、数量、可能的连接关系 | 谁拥有设备会话、动作顺序、安全条件 |
| 通信协议 | 字段、命令、样例报文 | 当前现场版本、超时/重试/恢复策略 |
| 口头补充 | 现场痛点和操作习惯 | 是否已经成为正式需求 |
| 现有代码/配置 | 当前真实实现 | 当前实现是否就是目标设计 |
材料版本、脱敏状态和可外发范围由项目规则决定。Agent 负责读取和交叉验证事实，不应该把“请确认协议里有没有 CRC”这种自己能查的问题重新问给用户。
2. 第一次理解：先区分 Facts / Inference / Decisions
第一次任务只要求理解项目，不写代码。
推荐输出不是一份长 PRD，而是：
text
Facts
= 材料直接支持的事实
Inferences
= 从常见工程经验推断、但当前项目未确认的内容
Decisions / Frontier
= 会改变业务结果、现在必须由项目人员决定的问题
Deferred
= 不阻塞当前版本的问题当时 AI 初判中出现过这类问题：
| AI 初判 | 后续处理 |
|---|---|
| 系统需要自动试验流程 | 基本方向成立，但状态和后果需要进一步确认 |
| 所有参数运行中可改 | 被项目人员否定，关键参数仅允许特定状态修改 |
| 异常后直接结束 | 证据不足，必须按事件类型决定 AlarmOnly / InterlockFault / Recovery |
| 主界面放全部配置 | 未采用，现场高频任务优先，低频配置转二级页 |
问题不在于 AI 会不会列功能，而在于它容易把“常见工业软件做法”补成当前项目要求。
3. Frontier：只问真正阻塞当前设计的问题
假设当前已经知道设备、主要页面和通信方式，Frontier 可能只剩：
text
1. 通信中断时是否必须停止当前试验？
推荐：按设备安全后果区分，不统一默认停机。
2. 哪些参数在 Testing 状态允许修改？
推荐：只开放明确安全且设备支持热更新的参数。
3. Stop 后下一次任务能否直接恢复，还是必须重新 SelfTest？
推荐：依据设备状态可信度和项目安全要求决定。每轮只问 2–5 个当前可决定、且会改变实现的问题。Blocking Frontier 清零以后就进入设计，不为了“需求完整”继续追问未来版本问题。
4. 从主流程进入状态机，但不要预设异常后果
整理后的正常路径可以是：
text
LoadConfig
→ Connect/Check
→ SelfTest
→ Ready
→ ApplyParameters
→ Testing
→ Resting
→ ...
→ Completed这只是案例项目的一种结构。
对于通信断开，不应该预先写成统一：
text
断线 → 关闭输出 → 保存数据 → FaultStop更合理的是先分类：
text
CommunicationLost
↓
当前设备是否安全关键？
↓
当前动作是否还能可信继续？
↓
Information / Advisory / AlarmOnly / InterlockFault
↓
对应恢复策略例如普通监测设备丢失可能只报警并继续；控制高压或运动设备的关键链路丢失则可能必须联锁停止。具体后果属于项目业务/安全决策。
5. 页面结构从操作员任务出发
AI 第一版界面可能信息很全，但“信息齐全”不等于好用。案例中的人工反馈聚焦于：
- 关键设备/试验状态持续可见；
- 高频操作不用跨多个页面找；
- 曲线按业务语义分组；
- 主界面不被低频配置和维护字段占满；
- 操作员摘要与底层诊断分层。
因此页面可以拆为：
- 主界面：核心状态、关键值、试验进度、高频动作；
- 配置页：任务参数和低频系统设置；
- 历史页：查询、导出、追溯；
- 报警/事件页：等级、时间、状态、处理结果；
- 维护诊断：原始协议、错误码、版本和设备细节。
界面骨架可以先接模拟数据；效果图阶段不要求同时改真实通信。
6. 通信、解析、显示和保存要有边界
案例采用的目标数据流类似：
text
设备会话
→ RX/TX 原始数据
→ 协议解析
→ 业务数据/状态
├─ UI 展示
├─ 数据保存
└─ 日志/事件关键不是固定要求必须有某个 Queue 或某个类，而是：
- 接收路径不能被不必要的磁盘/UI 工作阻塞；
- 原始证据能追溯到业务值；
- UI 与正式保存不互相当 Source of Truth；
- Stop/Dispose 能结束当前会话，不留下第二任务或重复订阅；
- 协议异常能用 Fake/Replay 重现时优先不用真机试错。
7. 任务拆分按“可验证闭环”，不是固定按层
大型新项目需要任务拆分，但任务卡强度可以分级。
新子系统 / 高风险任务
建议明确：
text
Goal
ConfirmedConstraints
ExpectedChangeSurface
NonGoals
Verification
HardwareBoundary（若有）已明确的小实现
不需要再填一张完整任务卡，Compact Brief 足够。
拆分示例
| 任务 | 目标 | 主要证据 |
|---|---|---|
| 建工程骨架 | 能启动最小应用 | affected build |
| 主界面骨架 | 操作路径和状态区域正确 | V1 + 人工 UI 检查 |
| Fake 通信链 | 命令/响应可重复 | V2 focused |
| 主状态机 | 正常/暂停/停止/恢复规则可验证 | V3 workflow |
| 数据链 | 采集、展示、保存职责清楚 | Replay / long-run sample |
| 真机接入 | 在授权条件下验证真实设备 | HardwarePending → HITL evidence |
不要因为“任务卡没有禁止文件列表”就阻止一个已经边界清楚的小任务；真正需要阻塞的是业务后果、安全条件或接口契约仍然未知。
8. 验收证据按风险，而不是每项都全量
| 方向 | 典型证据 |
|---|---|
| UI | V1 build + 目标分辨率/状态检查 |
| 通信 | Fake/Replay、原始报文、超时/异常路径 |
| 协议 | 正常帧 + 与本协议实际相关的异常样本 |
| 数据 | focused save/read/compatibility |
| 状态机 | V3 workflow / interlock / recovery |
| 性能 | 同场景前后基线对比 |
| 真机 | 授权后的 HITL 记录；没有就 HardwarePending |
“所有新项目都必须测半包、粘包、CRC”同样不是通用规则。例如 SCPI 文本会话与自定义二进制 TCP 协议需要的验证集就不同。
9. 这个案例最终留下什么
真正值得长期保留的不是整段聊天，而是：
- 项目稳定业务术语 →
CONTEXT.md； - 项目特有设备事实/历史坑 →
.agent-memory； - 难逆且非显然的长期取舍 → ADR；
- 多项目重复有效的方法 → Skill/reference；
- 测试和现场证据 → 对应测试/交付记录。
相关方法：
本案例一句话总结
新项目可以走完整工程路线，但完整不等于固定：Facts 由 Agent 查，Decisions 只问当前 Frontier；设计和验证按真实风险展开，不把示例状态、异常后果和测试矩阵当成所有项目的默认答案。