why-挑战
- 共性问题：忽视人的现实工作模式
问题 1：忽视认知负担管理两个工具都假设人能理解并遵循复杂流程、维护大量结构化文档、记住所有规范和约束。但现实是：土办法最管用。工具应该适配人的工作模式，而不是强行改变它。
问题 2：忽视"执行过程"的价值只关注"规范"和"结果"，忽视"过程"中的知识价值。
问题 3：忽视复利效应的关键性传统工具：帮你"做事"
复合工程：帮你"越做越快"
传统工具：每次都是新的开始
AI 工程化：每次都站在上次的肩膀上
问题 4：Spec 详细程度的悖论规范驱动开发有一个根本性的矛盾：
Spec 越详细 → 越接近代码本身 → 维护两份"代码"
Spec 越简略 → 越难指导 AI → 失去规范的意义
详细 Spec 的问题：当 Spec 详细到可以精确指导 AI 生成代码时，它本身就变成了另一种形式的"代码"，你需要同时维护 Spec 和 Code 两套产物，且要保持同步代码改了 Spec 要改，Spec 改了代码要改——双倍维护成本
开发者工作 / 人能做到AI不能做到的事
需求的理解
深入理解业务需求，识别核心功能点和约束条件；
技术需求与业务需求的关联分析，确保技术实现与业务目标一致；代码仓库的理解
项目架构与模块划分的理解，确保新代码与现有架构保持一致
关键接口与数据流理解，确保新功能与现有系统良好集成；
如何提升和审核ai识别代码仓库中相关文件，了解现有实现和架构设计；
如何升和审核ai建立需求与代码的映射关系，为后续提示词设计提供依据
- 提前审核ai代码
要求AI Coding结合这些信息生成开发概要或大纲，先不生成代码
人工审核生成的开发概要，对不正确或不完善的部分进行指正，审核时应重点关注架构设计的合理性、技术选型的恰当性
上层
AI 工程化的解法：不追求详细 Spec，而是分层概要 + 代码指针
概要层帮助 AI 快速定位到代码索引，避免维护一份"像代码一样详细的 Spec 文档"
细节层直接读代码
架构设计
- spec文档维护
以.md文件作为核心文档进行开发指导，确保文档与代码保持同步更新
文档不仅是信息载体，更是开发过程的重要指导工具
原则 1：分层式信息组织
AGENTS.md # 项目记忆入口（每次会话自动加载）
.codebuddy/ # AI 自动化配置
│ ├── agents/ # Agent 定义（决策层）
│ ├── commands/ # 命令入口
│ └── skills/ # Skill 定义（执行层）
requirements/ # 需求管理
│ ├── INDEX.md # 需求索引
│ ├── in-progress/ # 进行中需求
│ └── completed/ # 已完成需求
context/ 项目知识库
├── business/
│ └── 活动业务边界.md ← 概要层（意图识别时加载）
├── tech/
│ └── Apollo配置规范.md ← 技术层（方案设计时加载）
└── experience/
├── 商品发放历史问题.md ← 经验层（实施前加载）
└── 雅典娜配置注意事项.md ← 详细层（配置时加载）
沉淀格式：记录什么？
具体触发点：
├── 需求完成时 → 提取可复用经验
├── 遇到问题解决后 → 记住这个坑记录
├── 代码提交时 → 检查是否有值得记录的代码设计
└── 流程优化时 →检查是否有值得记录的优化设计
沉淀格式：记录什么？
context/experience/商品发放-钱包选择问题.md
问题描述
商品发放时选错钱包类型，导致用户领取失败
触发条件
- 需求涉及商品发放
- 商品类型为虚拟商品
解决方案
虚拟商品必须发到虚拟钱包，实物商品发到实物钱包
具体判断逻辑见 Apollo 配置：xxx.wallet.type
校验方式
检查 goods_type 与 wallet_type 的匹配关系
关联文档
- context/tech/Apollo配置规范.md
- context/tech/services/商品服务技术总结.md
agent的分布式计算
复杂任务长对话超出了单一agent的上下文
将复杂任务进行拆分成多个子任务，多个agent分布式处理
agent之间如何沟通：
方法1）由主agent作为桥梁沟通，本质上是获取子agent的对话上下文
方法2）通过结构化状态文件来进行信息传递
多人开发协作代码合并问题
多feature功能点并行开发
项目级文档沉淀，其他人新开会话能快速基于项目级文档了解项目规范风格
代码划分模块，改动一个feature不影响到其他模块
抽象公用skill，减少冗余代码
知识积累沉淀
传统开发：累积技术债务 → 每个功能增加复杂性 → 代码库越来越难维护
复合工程：每个功能产出文档模式 → 创建可复用组件 → 建立减少决策疲劳的约定 → 知识在团队中复合增长
开源组件问题
speckit 的核心缺陷问题
问题1：流程过于理想化speckit 的 Constitution → Specify → Plan → Tasks → Implement 流程假设：需求是清晰的可以一次性规划按阶段线性推进但企业真实场景是：需求动态变化多方并行博弈持续扯皮调整
问题 2：无法处理"考古"需求speckit 从零开始定义，但真实开发必须"考古"：历史坑点在哪？现有能力有哪些？配置规范是什么？
问题 3：知识不会沉淀
缺失机制：❌ 实施过程中发现的坑不会被记录❌ 排查信息丢失❌ 下次遇到类似问题还得重新排查
问题 4：宪章系统的僵化9 条不可变原则固然保证质量，但：✅ 适合标准化项目（Demo、开源库）❌ 不适合企业定制场景（历史债务、框架限制、合规要求）openspec 的核心缺陷
问题 1：Delta 机制的理论美好与现实骨感假设需求可以"提案化"，但企业真实场景是多线并行、动态调整、持续扯皮。
问题 2：Fail-Fast 的代价理论上保证一致性，实际上成为阻塞点。人的认知窗口有限，很难手动解决复杂冲突。
问题 3：强依赖命名的脆弱性产品、运营、研发对同一个需求有不同表述，命名不一致导致归档失败。
问题 4：Archive 只是"合并"，不是"学习"F(CurrentSpec, DeltaSpec) → NewSpec
缺失的维度：
F(CurrentSpec, DeltaSpec, Context, Lessons) → NewSpec + Knowledge
↑ ↑
实施上下文 经验教训
