无论是需求、规范还是用户故事，用于指导代码实现的任何信息，都必须具备一些关键特质（如敏捷方法中的 INVEST 原则）。随着人工智能逐渐参与代码生成，需求不仅要满足人类开发者的理解，还需要更加明确、结构化，以便 AI 能正确、可靠地生成符合项目约束的代码。因此，编写需求时标准更高，既要清晰给人看，更要让 AI 能"看懂"并正确实现。
本文是系列文章的第一部分，重点讨论确保需求本身的质量——需求是否被正确记录、是否正确、是否完整。这是所有后续工作的基础。
文档化
软件需求必须被记录下来，而不能仅仅存在于我们的脑海中。只要易于维护，文档可以尽可能轻量级。毕竟，文档的目的是成为一个单一的事实来源。
当我们说需求必须"文档化"以便人类开发人员使用时，我们的意思是它们需要被记录在某个可访问的地方（维基、需求文档、用户故事等）。如果它们只存在于某个人的脑海中，或者分散在聊天消息中，它们可能就不会非常有效。这有助于确保一致性，提供一个参考点，并有助于新员工入职。尽管轻量级文档通常是首选（例如用户故事），但通常有一个隐含的理解，即人类可以通过对话、经验和共享上下文来填补空白。
但对于 AI 来说，情况就完全不同了。 对于人工智能代码生成，"文档化"特质承担了更具挑战性的角色：
1. 文档是主要输入
人工智能代码助手不会参加计划会议。它们可能无法实时提出澄清问题（尽管一些工具允许交互式细化）。目前，它们缺乏人类开发人员多年的情境经验。书面需求文档可能是人工智能为特定任务接收到的最直接且通常是唯一的指令集。其质量可以直接决定生成代码的质量。这就像你给 AI 一张地图，如果地图画错了，AI 就会走错路。
2. 需要机器可解释性
尽管我们可以很好地理解自然语言，即使存在一些歧义，但人工智能模型在清晰、结构化且无歧义的输入下表现最佳。这意味着文档的格式和精确性可能是一个游戏规则改变者。模糊的语言可能导致人工智能做出不可预测或错误的假设。就像你跟人说话，对方可能能理解你的意思，但跟 AI 说话，必须说得清清楚楚，不能有歧义。
3. 结构化格式有助于一致性
我们可以使用 Gherkin 进行行为驱动开发（BDD），特定的提示模板，甚至是像 JSON/YAML 这样的结构化数据格式来处理类似配置的需求。使用预定义的结构或模板来记录需求是非常有用的。这样，必要的细节（如错误处理、边缘情况和非功能性需求）可以被一致地考虑并提供给人工智能。这可以导致更可预测和可靠的代码生成。就像填表格，格式统一了，AI 就能更好地理解。
4. 单一事实来源至关重要
因为文档是提供给人工智能的规范，确保它是权威的、最新的版本至关重要。在重新生成之前，必须在文档中反映任何更改。如果文档版本不一致，AI 可能会用旧版本生成代码，那就麻烦了。
正确性
我们必须正确理解系统需要什么以及不需要什么。这听起来可能很简单，但有多少次我们实现了错误的需求？在这里，输入错误，输出错误（GIGO） 规则适用。就像做菜一样，如果食材不对，再好的厨师也做不出好菜。
对于人工智能代码生成，正确性的重要性可以通过以下方面来评估：
1. 人工智能按字面执行
人工智能代码生成器是将指令（需求）翻译成代码的强大工具。然而，它们通常缺乏对领域的深入理解。目前，它们缺乏质疑指令本身是否合乎逻辑或是否符合更广泛的业务目标的"常识"。如果你给人工智能一个表述明确但功能错误的需求，人工智能可能会生成完美实现该错误功能的代码。这就像你让 AI 去"买苹果"，如果需求写的是"买红色的苹果"，AI 就会去买红苹果，即使你实际想要的是 iPhone。
2. 减少隐式纠正的机会
我们可能会阅读一个需求，并根据我们的经验或对项目背景的理解，发现逻辑错误或与已知业务规则相矛盾的地方。我们可能会说："你确定这是对的吗？通常在这种情况下我们做 X。"这为早期发现错误需求提供了一个宝贵的反馈循环。人工智能不太可能提供这种主动的、情境感知的合理性检查。它通常假设接收到的需求是意图中的事实。AI 不会质疑你，它只会照做，所以需求必须是对的。
3. 验证是关键
确保正确性的责任主要落在需求定义和验证过程上，在人工智能参与之前。定义和审查需求的人必须严格确认他们要求的是真正需要的东西。在把需求交给 AI 之前，一定要仔细检查，因为 AI 不会帮你发现需求错误。
完整性
这关乎没有缺失的属性或功能。尽管不完整的需求是一个问题，但我们可以推断缺失的细节，提出澄清问题，或者依赖隐含的知识。然而，对于人类来说，这并不总是如此！即使经过数小时的会议和讨论，需求也可能仍然不完整。
在人工智能生成代码的情况下，我看到人工智能助手朝两个方向发展。有些情况下，人工智能助手生成了明确陈述的内容。由此产生的差距导致功能不完整或人工智能做出了可能错误的假设。也有一些情况下，人工智能助手发现了缺失的属性并提出了建议。但你不能指望 AI 总是能发现缺失的部分，所以最好一开始就把需求写完整。
在任何情况下，为了完整性，我认为我们仍然值得尽可能明确。需求不仅必须详细说明"快乐路径"（正常流程），还必须包括：
- 边缘情况：明确列出已知的边缘情况。比如用户输入为空、数据超出范围、网络超时等。
- 错误处理：指定如何处理错误（例如，特定的异常、返回代码、日志消息）。不要只说"处理错误"，要说清楚怎么处理。
- 非功能性需求（NFRs）：性能目标、安全约束（输入验证、输出编码、认证/授权点）、可扩展性考虑以及数据处理/隐私规则必须明确说明。这些往往容易被忽略，但对 AI 来说很重要。
- 假设：明确列出所做的任何假设。比如假设用户已经登录、假设数据格式正确等。
总结
在人工智能时代，需求的基础质量变得更加重要。文档化、正确性、完整性是确保需求本身"合格"的三个关键特质：
- 文档化确保需求被正确记录，成为 AI 可以理解和使用的输入
- 正确性确保需求本身是对的，避免"垃圾进，垃圾出"
- 完整性确保需求没有遗漏，包含所有必要的细节
只有需求本身的质量得到保证，我们才能进入下一步：确保需求能被正确理解。在下一篇文章中，我们将讨论无歧义性和一致性，这是确保需求表达清晰、易于理解的关键特质。