你让它加个小功能，它顺手把你核心逻辑“优化”了；代码虽然能跑，但设计方向完全偏离。在复杂业务中，AI 编码导致频繁返工的根源是什么？本文将带你拆解 AI 编码的“控制难题”，并分享一套基于结构化提示词的开源解决方案（OpenSPDD）。模型越强，你越需要把意图和边界写清楚。
一个反直觉的观察
AI 编码工具越来越强。Claude Code、Cursor、Codex、各种 Coding Agent……模型能力在飞速提升。
但如果你在做有一定复杂度的业务开发，并且会认真审查 AI 生成的代码，可能遇到过这些情况：
- 你让它实现一个功能，它擅自加了你没要求的东西——你只要个简单注册，它给你上了 OAuth2 和风控
- 你让它做一个改动，它顺手"优化"了不该碰的代码，引入了你没预料到的副作用
- 你以为它"理解"了业务背景，结果生成的代码在技术上能跑，但设计方向和你的意图不一致
代码能跑，但需要返工。返工的原因不是"写错了"，而是"做多了"或"做偏了"。
这类问题不是每次都发生。简单任务上，AI 现在已经非常省心。但一旦涉及架构决策、业务边界、设计取舍——也就是"存在多种合理选择"的场景——AI 做偏的概率就会明显上升。
这让我开始思考一个问题：这些返工的根源，到底是 AI 能力不足，还是我们传达给它的设计意图不够精确？
基于这个思考，我做了 OpenSPDD（结构化提示词驱动开发工具），试图从提示词结构入手来缓解这个问题。在实践中有一些值得分享的思考。
能力与控制：一个关键区分
在展开具体讨论之前，有一个区分需要先建立，因为它是理解后续所有论点的基础。
AI 编码的改进可以发生在两个维度：
能力维度——AI 能否理解需求、能否生成正确的代码、能否推断出项目惯例。这个维度随模型进化在持续改善，毫无疑问。
控制维度——如何确保 AI 的理解和你的意图一致、如何在多种"正确"方案中选你要的那种、如何定义什么不能做。
这两个维度有交叉但不完全重叠。能力进步确实可以缓解部分控制问题——更大的上下文窗口、持久记忆、更好的对话式澄清，都在改善 AI 对设计意图的理解。但有一类控制需求，仅靠能力提升无法消除：当存在多种“正确”方案时，选哪一种是人类的权衡决策，而不是 AI 的逻辑推断。
这种“决策权衡”与“具体实现”的分离，并不是 AI 时代才出现的新命题。早在 1986 年，Fred Brooks 在探讨“本质复杂度”和“偶然复杂度”时，就一针见血地指出：软件最难的部分从来不是编码，而是规格与设计。
这也解释了在人类开发者的协作中，为什么“能力”永远无法替代“控制”。比如一个资深架构师，他的编码能力毋庸置疑，但企业依然要求他输出设计文档、沉淀 ADR（架构决策记录）。因为即便他再聪明，团队也需要共享理解、决策需要可追溯、未来的维护者需要上下文。同理，飞机的自动驾驶再智能，飞行计划也不会消失——不是因为自动驾驶能力不行，而是因为整个协作系统需要一个共享的、可验证的基准。
现在，当 AI 在编码能力上越来越逼近甚至超越人类专家时，它不可避免地继承了同样的协作困境：那些未被记录的决策，换一个 Agent、开一次新对话，就需要重新来过。
甚至，AI 让这个老问题变得更加紧迫。不是因为返工的绝对成本更高（AI 重新生成很快），而是因为偏差更隐蔽。AI 生成的代码通常质量不低、风格一致，很容易通过粗略的 review。但设计方向上的偏移——用了错误的架构模式、多做了不该做的事——往往要到后续迭代甚至上线后才被暴露，那时的修正成本才是真正高昂的。
本文不试图提出新的理论洞见。它聚焦的是一个实践问题：这些已知的控制需求，如何落地成 AI 编码工具链中可操作的工作流？
为什么控制这么难
LLM 的歧义放大效应
LLM 不是确定性的编译器。当输入存在多种合理解读时，它会选择其中一种来执行——而你往往无法预知它选哪种。问题不在于"AI 每次给不同结果"，而在于同一句自然语言本身就承载了多种可能的意图，AI 会把这种输入层面的歧义放大为输出层面的差异。
更强的 AI 确实能降低部分歧义。它可以扫描你的代码库，推断出项目的主流模式——比如大多数 Service 用的是构造器注入，API 风格是 RESTful。这类编码风格和惯例层面的歧义，AI 越强越能收敛（前提是代码库本身足够一致）。
但有一类不确定性，AI 能力再强也无法靠推断来降低：
- 这个功能应该用事件驱动还是同步调用？
- 应该支持多币种还是只做单币种？
- 哪些东西不能做、不能碰？
这些不是"推断"问题，是"决策"问题。不存在客观上"更对"的答案，取决于你这个项目当下的具体权衡。代码库里如果没有做过类似决策，AI 没有推断的依据；即使有先例，AI 也分不清"这是刻意选择"还是"历史妥协"。
这就是控制维度的核心挑战——不是帮 AI 推断编码风格，而是把人类的设计决策、架构权衡和约束边界精确传达给 AI。
"负空间"容易被忽略
AI 编码中导致返工的一个常见原因，不是"缺了什么功能"，而是 AI 多做了什么、做偏了什么：
你: "实现这个 Service"
AI: [加了一层你没要求的缓存]
[自己决定了异常重试策略]
[把事务边界放在了调用方而不是服务方]
每一条单独看都"合理"，但加在一起就偏离了你的设计意图。
人类开发者有隐性的专业判断来自我约束——"这个不该我决定"、"这个超出当前 scope"。但 AI 缺乏这种边界感。如果提示词只定义了"正空间"（做什么），而没有定义"负空间"（不做什么），AI 就容易在合理的范围内"过度发挥"。
定义负空间不只靠自然语言声明。更可靠的方式是语义声明加上机器可校验的约束——前者是软约束，后者是硬约束。但显式声明负空间，即使只是软约束，也比完全不声明要好。
设计意图容易随时间丢失
考虑这个场景：
v1.0: Plan 定义 "订单服务，同步处理，单币种 USD"
AI 据此生成代码
↓
架构评审: "为了可扩展性，改成异步事件驱动"
业务决策: "欧洲市场需要支持 EUR"
↓
v1.1: 团队重构为异步 + 多币种
↓
⚠️ Plan 仍然描述的是 "同步处理，单币种"
↓
v2.0: 需要生成 "退款" 功能
Agent 扫描代码库后，大概率能看到异步模式和多币种支持，生成的退款代码在技术层面应该是兼容的。但 Agent 不知道的是：
- 异步化的原因是什么？是解决性能瓶颈，还是为未来的消息队列迁移做准备？退款是否也必须走异步链路？
- 多币种是"只加了 EUR"还是"要做通用多币种架构"？退款需要支持任意币种吗？
- 哪些 v1.0 的代码是"已确认保留的"，哪些是"还没来得及清理的"？
这些都是设计意图——代码里看不出来，普通的执行计划也很少涉及。代码库扫描能防止技术层面的冲突，但无法防止设计方向的偏移。
值得注意的是，主流工具厂商也在朝同一个方向探索：Claude 官方为 CLAUDE.md 的定位是提供"它无法从代码推断的持久上下文"，Codex 建议把 agent 的错误假设修正写进 AGENTS.md。厂商的做法不等于真理，但当多个独立团队不约而同地在代码扫描之外增加显式的上下文机制时，这至少说明：仅靠代码扫描在实践中是不够自足的，这是一个被反复验证的经验判断。
解读空间难以收窄
需求: "创建用户注册服务，包含邮箱验证和密码加密"
AI-A: 简单的 Service，validate + encode + save，50 行
AI-B: 加了事件发布、审计日志、异步邮件队列，200 行
AI-C: CQRS 模式，Command/Query 分离 + Event Sourcing，500 行
三种都满足字面需求，但复杂度、维护成本、架构含义完全不同。
模糊性在人类开发中可以通过对话化解。AI 工具也在这方面进步——Cursor 的 Plan Mode 会主动提问，Claude Code 会先澄清再动手。但在复杂场景中，有些歧义靠对话难以彻底消除，因为开发者自己可能没意识到某些决策需要显式化。一个结构化的框架可以起到 checklist 的作用，帮助发现那些"你不知道你需要决定"的决策点。
当前 AI 编码工具在做什么
主流工具已经在"把设计意图传达给 AI"这个方向上做了大量工作，且成效显著：
- Cursor 的 Agent 模式能深度扫描代码库、推断项目惯例、主动澄清需求，Plan Mode 可以产出带文件路径和代码引用的结构化计划。对于项目内部的编码风格一致性，它已经做得很好。
- Kiro 把 specs 定义为 structured artifacts，分成 requirements、design、tasks 三个文件，在规格的结构化程度上走得比较远。
- Claude Code 强调先探索代码库、先澄清需求再执行。
CLAUDE.md用来记录 coding standards 和 workflow rules，hooks 机制支持机器可校验的自动化约束。 - Codex 的
AGENTS.md允许固化项目约定和反复出现的错误修正，支持目录级别的上下文配置。 - GitHub Copilot 通过
copilot-instructions.md支持项目级别的规范定义，copilot-prompts/目录可存放可复用的提示词模板。
这些工具已经远超"简单的代码补全"，都在朝 spec-first 的方向演进，而且解决了很大一部分实际问题——尤其是编码惯例、命名风格、项目结构这些可以从代码库推断的方面。
然而，如上一节所讨论的，有一类问题——设计决策、架构权衡、负空间约束——仅靠代码库扫描和对话式交互仍然难以完全覆盖。这不是工具不够好的问题，而是"把设计意图精确传达给 AI"这件事本身存在结构性挑战。
代码库扫描：有价值，但有边界
代码库扫描是当前 AI 编码工具最重要的能力之一。理解它的边界，有助于我们更好地配合它。
代码记录"是什么"，不记录"应该是什么"。
Agent 扫描代码库后发现:
- ServiceA 用了字段注入
- ServiceB 用了构造器注入
- ServiceC 用了 setter 注入
Agent 的困惑: "这个项目的注入规范到底是什么？"
真相: ServiceA 是三年前的遗留代码，ServiceB 是重构后的新标准，ServiceC 是实习生写的
代码库是历史决策的累积，其中混杂着最佳实践、历史遗留和技术债务。CLAUDE.md 和 AGENTS.md 的一个重要用途，就是帮 Agent 区分"应该遵循的规范"和"需要清理的遗留"。
这也回应了前面提到的一个前提：AI 推断编码惯例的能力，依赖代码库本身的一致性。但这个前提并不自动成立——三种注入方式共存，正是因为项目缺乏对"应该用哪种"的显式约定。这就形成了一个循环：AI 需要一致的代码库来推断规范，但代码库的一致性本身就需要某种形式的显式约束来维护。没有控制，就没有一致性；没有一致性，AI 的推断能力就打了折扣。
代码不记录"为什么"。
Agent 扫描到: PaymentService 使用了最终一致性
Agent 无法知道:
- 这是深思熟虑的架构决策？还是临时妥协？
- 当时为什么没用强一致性？是性能考虑？还是技术限制？
- 未来是否计划迁移到强一致性？
代码是"决策的结果"，不是"决策的过程和理由"。
代码库是向后看的，设计意图是向前看的。
场景: 要在现有系统上添加"多租户"支持
Agent 扫描代码库: 当前是单租户架构
Agent 的推断: 继续按单租户模式生成代码
但设计意图是: 这次就是要改成多租户
当你的目标是改变现有架构时，扫描现有代码恰恰可能把 Agent 引向错误的方向。
从代码"逆向工程"设计意图是有损的。
一段代码可能对应多种设计意图：
if (user.getRole() == Role.ADMIN) {
return allRecords();
} else {
return userRecords(user.getId());
}
这可能意味着：简单的角色权限控制（够用就行）；临时方案，未来要迁移到 RBAC；产品明确要求只区分管理员和普通用户。代码一样，但三种意图下，下一步的开发方向完全不同。
代码是设计的一种投影，从投影反推原始意图，信息必然是不完整的。
代码库扫描、显式的设计意图声明、机器可校验的约束——三者是互补的，不是互斥的。业界的实践也在朝这个方向收敛：各主流工具都在代码库扫描的基础上，增加了 repo-level 的指令文件来补充那些无法从代码推断的上下文。
结构化提示词的一种尝试
问题已经明确：设计决策、架构权衡、负空间约束这类信息，需要被显式表达。但"显式表达"本身也有高低之分。
以"创建用户注册服务"为例，对比两种表达方式：
自然语言需求描述：
创建用户注册服务。处理用户注册的业务逻辑，包括邮箱查重、密码加密和用户保存。
使用构造器注入，注入 UserRepository、EmailValidator 和 PasswordEncoder。
如果邮箱已存在则抛异常。新用户状态为 PENDING_VERIFICATION。
加 @Service 和 @Transactional 注解。
这已经比一句"创建 UserRegistrationService"好得多了。但请注意它遗漏了什么：没有说明业务背景（为什么只做邮箱注册？），也没有定义边界（不要引入 OAuth？不要加缓存？）。这不是因为写的人不够仔细——而是在缺乏结构引导时，人们天然倾向于描述"做什么"和"怎么做"，而遗漏"为什么"和"什么不能做"。
结构化框架引导下的表达（部分节选）：
## Requirements (为什么做)
- 业务背景: MVP 阶段，只需邮箱注册，不需要 OAuth
## Operations (怎么做)
### Create Service Implementation - UserRegistrationServiceImpl
1. Responsibility: Handle user registration business logic
2. Location: `com.example.user.service.impl.UserRegistrationServiceImpl`
3. Dependencies (constructor injection):
- `UserRepository userRepository`
- `EmailValidator emailValidator`
- `PasswordEncoder passwordEncoder`
4. Annotations: `@Service`, `@Transactional`
5. Method `register(UserRegistrationRequest request)`: UserRegistrationResponse
- Logic:
1. Call `emailValidator.validate(request.getEmail())`
2. Call `userRepository.existsByEmail(request.getEmail())` → if true, throw `EmailAlreadyExistsException` with message "Email already registered"
3. Call `passwordEncoder.encode(request.getPassword())` → get encodedPassword
4. Create User entity with status `PENDING_VERIFICATION`
5. Call `userRepository.save(user)` → get savedUser
6. Return UserRegistrationResponse with savedUser.getId()
## Safeguards (什么不能做)
- 不引入 OAuth、社交登录等第三方认证
- 不添加自定义缓存层
- 不修改现有 User 实体的字段定义
差别不只是"详细程度"。后者在结构上引导你去思考和声明那些容易被遗漏的维度——尤其是 Safeguards（不做什么）和 Requirements（为什么做）。它起到的是一种 checklist 效应：不是帮你写更多字，而是帮你少遗漏关键维度。
但 checklist 效应只是起点。一张提问清单（"你定义了不做什么吗？"）可以起到提醒作用，但它的产出是回答者脑中的确认，不是一份可被消费的工件。结构化框架的额外价值在于：它不仅提醒你思考这些维度，还为每个维度提供填写的结构，产出一份可以直接喂给 AI 执行、可以版本控制、可以在团队间流转的文档。从"提醒你想到"到"帮你写下来并让工具链消费"——这是 checklist 和 framework 的区别。
有人可能会想：我不需要前置这么多结构，直接让 AI 做，做偏了再改就好。迭代修正在单次对话中确实高效——"去掉缓存"、"改成同步"，几轮就能调对。但问题在于：这些修正中隐含的决策散落在对话历史中。下次开新对话，同样的偏差可能重现；团队其他人启动的 Agent 不知道这些约定；换了模型或工具，历史对话不可迁移。迭代修正解决的是"这一次"的问题，结构化提示词解决的是"每一次"和"每个人"的问题。
"结构化提示词"是一种理念，不是固定格式。行业里已经有多种实践：Kiro 的 requirements/design/tasks 三层结构、Claude 的 CLAUDE.md、Codex 的 AGENTS.md、传统的 ADR。这些实践各有侧重，但都在解决同一类问题。
OpenSPDD 提出的 REASONS Canvas 尝试做的，是把这些分散的关注点整合成一个AI可执行的、可嵌入 AI 编码工具链的统一框架——一个 7 维度的 checklist：
┌─────────────────────────────────────────────────────────────────────┐
│ REASONS Canvas │
├─────────────────────────────────────────────────────────────────────┤
│ │
│ R - Requirements 为什么做 ┐ │
│ E - Entities 涉及什么概念 ├─ 战略层 (Why/What) │
│ A - Approach 用什么方式 ┘ │
│ │
│ S - Structure 组件如何组织 ┐ │
│ O - Operations 具体怎么做（精确到方法签名）├─ 实现层 (How) │
│ ┘ │
│ │
│ N - Norms 按什么标准（应该怎样） ┐ │
│ S - Safeguards 什么不能做（不能怎样） ├─ 约束层 (Boundary) │
│ ┘ │
│ │
└─────────────────────────────────────────────────────────────────────┘
这三层对应前文讨论的三类控制问题：
- 战略层告诉 AI "为什么"和"做什么"，应对上下文缺失和设计意图丢失
- 实现层告诉 AI "精确怎么做"，收窄解读空间
- 约束层告诉 AI "什么不能做"，应对 AI 的"过度发挥"
它不是"唯一正确的方式"，而是一种通过结构引导来减少遗漏的思路。问题从来不是"要不要表达设计意图"——这一点行业早有共识。真正的难点是：在 AI 编码的快节奏工作流中，如何用一种足够轻量、可嵌入现有工具链、能跟随代码演进的方式来做这件事。REASONS Canvas 是对这个实践问题的一种回答。如果你已经在用 CLAUDE.md 或 AGENTS.md 并且运作良好，那也是有效的方式——两者解决的粒度不同，是互补而非替代。CLAUDE.md / AGENTS.md 通常是 repo 级别的约定：记录的是"这个项目怎么做事"（用构造器注入、API 风格是 RESTful、错误处理用统一格式）。REASONS Canvas 针对的是 feature 级别的决策：记录的是"这个具体功能怎么设计"（这个支付模块用同步调用、只做单币种、不加缓存层）。前者像团队的编码规范手册，后者像某次架构评审的结论。两层都有价值，缺哪一层取决于你的痛点在哪。
不过要说清楚一点：结构化提示词不是让 AI 完全不再"解读"，而是把它的解读空间压缩到更小、更可控的范围。它降低的是不必要的解读，不是消灭解读。
AI 变强了，结构化提示词还需要吗？
有人会问：AI 进化到"足够聪明"，是不是结构化提示词就可以省了？
在写脚本、改配置、加日志这类简单任务上，确实可以——AI 变强让这些事情越来越省心。
但在涉及架构决策、业务规则、多人协作的场景下，我的看法是：恰恰更需要。
假设 AI 达到"完美"——无限上下文、零幻觉。面对"给我一个支付系统"这句话，一个真正"完美"的 AI 最可能的反应不是直接生成代码，而是反问——就像今天的 Cursor Plan Mode 和 Claude Code 已经在做的那样：
完美AI: "你要事件驱动还是同步调用？多币种还是单币种？
对账用最终一致性还是强一致性？"
但这正好说明了问题：即使 AI 足够聪明到知道该问什么，这些决策仍然需要人类来做，并且需要被记录下来。
AI 的提问不产生决策，人类的回答才是。而如果这些回答只存在于一次性的对话中：
- 下次开新对话，同样的问题要重新回答
- 团队其他成员启动的 Agent 不知道这些决策
- 三个月后换了模型或工具，历史对话不可迁移
支付系统可以有 100 种"完美"的设计，每一种都是"正确"的，但只有一种是"你这个项目当下需要的"。这些选择需要被固化——不是固化在一次性对话里，而是固化在可持续消费的工件里。
回到"能力 vs 控制"的框架：AI 变强解决的是能力问题——理解得更准、生成得更好。但控制问题——如何在多种"正确"中选你要的那种、如何定义不能做什么、如何让不同时间点的不同 Agent 共享同一套决策——不会因为 AI 变强而消失。
协作时代的共享工件
软件开发本质上是分布式协作——无论参与者是人还是 Agent。而分布式协作有一个基本前提：参与者之间需要共享某种工件来协调行动。
这个共享工件可以有多种形式：
- 结构化设计规格（CLAUDE.md、AGENTS.md、REASONS Canvas 等）
- 机器可校验的约束（测试、类型系统、接口契约、Schema 等）
- 决策记录（ADR / Architecture Decision Record）
- CI 策略（pre-commit hooks、linters、自动化检查）
实际项目中，有效的协调通常是这些形式的组合，而不只依赖其中一种。
多 Agent 协作已经是现实：Cursor 可以启动子任务并行处理，Claude Code 支持多个 agent 实例协作。这些场景下，共享工件变得更加重要——每个 Agent 需要知道全局的架构决策和约束边界，否则并行执行的结果很可能互相矛盾。
即使只有一个 Agent，跨越时间后它面对的实际上是"不同实体"的问题：
T1: Agent-v1（GPT-5）开发了系统 v1
T2: Agent-v2（GPT-6）需要在 v1 基础上开发 v2
T3: Agent-v3（Claude-5）需要重构系统
如果没有外化的决策记录，Agent-v2 不知道 Agent-v1 为什么选了事件驱动而不是同步调用，Agent-v3 不知道哪些设计是"有意为之的权衡"，哪些是"历史遗留的妥协"。
共享工件不仅是空间维度上的协作基准，也是时间维度上的知识载体。
还有一个容易被忽视的角度：当人类从"执行者"退为"监督者"，人类对系统的理解反而变得更难。Agent 写了所有代码，人类需要某种"望远镜"来理解全局。结构化的决策记录可以充当这个望远镜。
不只是表达层——验证层同样重要
讨论到这里，必须强调一点：真正让 AI 输出可控的，不只是"表达得更结构化"，还需要机器可校验的验证闭环。
结构化提示词解决的是"表达层"——如何把设计意图传达给 AI。但它本质上是软约束：AI 可以参考，也可能偏离。
验证层提供的是硬约束——测试、类型检查、Schema 验证、Lint 规则、pre-commit hooks等。这些不依赖 AI 的"理解"，而是机械地检查输出是否符合规则。
更稳的组合是：
代码库扫描（理解现状）+ 结构化提示词（表达意图与约束）+ 自动化验证（机器校验关键规则）
任何单一层面都不是万能的。三层配合，才能在"AI 自主性"和"人类可控性"之间取得平衡。
适用场景与局限性
需要诚实地讨论结构化提示词（包括 REASONS Canvas）的适用边界。
适合的场景：
- 核心业务逻辑，需要长期维护、多人协作的系统
- 架构决策点，涉及重要权衡的设计选择
- 受监管领域，需要审计和可追溯性的场景
- 跨团队协作，多个 Agent 或人类需要共享理解的项目
不太适合的场景：
- 快速原型，探索性开发，预期会大量丢弃
- 一次性脚本，用完即弃，不需要维护
- 简单任务，改个 typo、加个日志，不值得投入额外的结构化工作
结构化提示词是重要决策的外化工具，不是所有 AI 编码任务的通用方法。过度使用反而增加心智负担，这和传统软件工程中"过度设计"的问题一样。
还有一个必须正面回应的问题：结构化提示词自身也会过时吗？
前文用"v1.0 的 Plan 到 v1.1 已经过时"来论证设计意图容易丢失，但同样的质疑完全适用于 REASONS Canvas——如果代码改了而 Canvas 没跟着更新，它就从"设计指南"变成了"误导性的过时文档"，比没有文档更危险。
这不是一个可以轻描淡写的问题。坦率地说，设计规格与代码的双向同步是当前最大的工程难题之一，尚未被任何方案完全解决。我们目前的做法是：在每次功能迭代后，手动运行 /spdd-sync（OpenSPDD提供的命令）让 AI 检测代码变更并更新对应的结构化提示词。这还不是一个强制性的流程，更多是团队约定——"改完代码，顺手同步规格"。它不完美，但在实践中行之有效：关键决策的变更基本能被捕捉到，结构化提示词不至于过时。未来的方向是把这一步自动化——比如每次代码更新后，自动触发同步检测，如果发现变更，则自动更新对应的结构化提示词。
展望
随着 AI 能力提升，一个明显的趋势是：结构化工件的生成越来越多地由 AI 辅助甚至主导完成。以 OpenSPDD 为例，当前工作流已经是：AI 分析业务需求和代码库（/spdd-analysis）→ AI 自动生成结构化提示词（/spdd-reasons-canvas）→ 人类审核关键决策 → AI 执行（/spdd-generate）→ 变更同步回提示词（/spdd-sync）。
如果这个趋势继续，一个可能的演进方向是：
当前： AI 辅助分析 → AI 生成结构化提示词 → 人类审核 → AI 执行
近期： AI 自主完成常规决策 → AI自主完成部分审核 → 人类只审核关键节点 → 多 Agent 协作执行
远期： Agent 自主生成并维护大部分结构化工件 → 人类抽检与治理
这个演进没有确定的时间表，是基于当前趋势的推测。
这里有一个看似矛盾的地方：如果 AI 最终能自主生成和维护这些结构化工件，那人类还需要关心这件事吗？
我的理解是：变化的是"作者"——从人写，到 AI 写人审，到 AI 自主维护。不变的是"需求"——复杂系统始终需要某种结构化、可共享、可追溯的中间产物来协调多个参与者的行动。就像编译器自动生成机器码不意味着指令集可以消失，AI 自动生成设计规格不意味着设计规格本身变得不重要。只是生产方式变了，存在的必要性没变。
也许未来它不再叫 prompt。也许它会演变成 Agent DSL、Agent 决策记录、Agent 可执行 spec、Agent 自动同步的契约文件等更特质化的概念。但它背后的需求不会消失。
结语
回到核心问题：AI 变强了，我们与 AI 协作的方式是否可以更随意？
在简单任务上，可以更轻。但在复杂系统里，恰恰相反。
理解这一点，我认为需要三个认知转变：
内容上，从"提示词"到"约束"。 问题不只是"怎么把需求说清楚"，而是"怎么把边界说清楚"。很多返工，不是因为 AI 没做，而是因为 AI 多做了、做偏了、替你做了不该由它拍板的决定。
时间上，从"一次性输入"到"持续演进的工件"。 真正有价值的，不是那一刻的 prompt，而是那份能跟着代码一起演进、能被后来者继续消费的中间产物。
受众上，从"人对 AI 的指令"到"决策外化的载体"。 结构化提示词的价值，不只是帮 AI 更好地生成代码。更重要的是，它把那些原本散落在人脑中、历史对话中、代码细节里的设计意图，外化成了一个更容易共享、复用、追溯和验证的载体——给 AI 消费，也给团队消费。
问题从来不只是"AI 够不够聪明"。更核心的问题是：当模型越来越强、协作越来越复杂时，我们是否把真正重要的东西——意图、边界、取舍——写成了 Agent 能稳定消费、团队能持续复用的形式。
如果你想尝试
用你已有的工具
不需要 OpenSPDD，你已经可以开始：
- Cursor：善用 Agent 模式和 Plan Mode，让 AI 在生成代码前充分澄清需求；用
.cursor/rules/目录固化项目约定 - Claude Code：维护好 CLAUDE.md，记录项目约定和设计决策；利用 hooks 实现自动化校验
- Codex：善用 AGENTS.md，把反复出现的问题和项目约定固化进去
- GitHub Copilot：利用
copilot-instructions.md定义项目规范，用copilot-prompts/存放可复用的提示词模板
体验 OpenSPDD
如果你想尝试 OpenSPDD 这种更结构化、体系化的方式：
brew install gszhangwei/tools/openspdd #MacOS
go install github.com/gszhangwei/open-spdd@latest #非MacOS，需要go环境
cd your-project
openspdd generate --all # 生成 SPDD 命令
# 在 AI 编码工具中使用：
/spdd-analysis @requirements/feature.md # 战略分析
/spdd-reasons-canvas @spdd/analysis/xxx.md # 生成结构化提示词
/spdd-generate @spdd/prompt/xxx.md # 按结构化提示词生成代码
/spdd-sync @spdd/prompt/xxx.md # 同步变更回提示词
OpenSPDD 已经在后端业务逻辑类的真实项目中使用。在我们的实践中，对于有明确业务规则的功能开发，结构化提示词带来的返工减少和方向准确性提升是显著的——一些原本需要数天反复调整的功能，在规格明确后可以在数小时内完成。当然，这个效率差异高度依赖项目类型和任务复杂度，不宜一概而论。工具仍在持续迭代中，欢迎尝试、提 issue 和 PR。
审视你当前的 AI 工作流
无论用什么工具，可以问自己几个问题：
- AI 是否经常"多做"或"做偏"？→ 可能需要更明确的边界定义
- 代码改了之后，之前的设计文档还准确吗？→ 可能需要更好的同步机制
- 团队成员用 AI 写的代码一致吗？→ 可能需要共享的约定文件
- 重要的设计决策有没有被记录？→ 可能需要 ADR 或类似机制
开放的问题
本文提出的是一种思路，不是定论。仍有很多问题值得探索：
- 结构化提示词的"最佳粒度"是什么？什么时候值得写，什么时候过度？
- 设计规格与代码的双向同步在工程上如何做到可靠？
- 不同团队、不同项目类型，需要什么样的结构化框架？
- 当 Agent 自主生成规格时，人类如何有效审核？
这些问题没有标准答案，需要在实践中探索。
本文探讨 AI 编码时代结构化设计意图表达的价值与局限。OpenSPDD 是其中一种尝试，欢迎试用和反馈。
这篇文章首发于我的微信公众号【Mod的AI探索】。
如果你对 AI 研发工作流、架构设计感兴趣，欢迎关注，我会定期分享深度的实战思考。
