add-implementation-requirement

添加实现要求

始终使用技能 load-plain-reference 检索 plain 语法规则，但仅限尚未检索过的情况。

工作流

1. 确定目标 .plain 文件。 如果存在歧义，请询问用户。
2. 读取文件，了解现有的实现要求、定义和功能规格。
3. 判断内容是否属于实现要求——必须描述如何构建，而不是要构建什么（后者应放在 ***functional specs*** 中）。
4. 按照以下规则起草要求。
5. 将其插入 ***implementation reqs*** 部分。
6. 再次读取文件，确认位置和语法正确。

适用内容

实现要求是指导代码生成的自由格式说明。常见内容包括：

• 技术选择：语言、框架、运行时版本
• 架构约束：模式、分层、依赖规则
• 编码标准：命名约定、风格指南
• 数据格式：序列化、编码、转换规则
• 错误处理：策略、重试逻辑、异常层次结构
• 算法描述：仅凭行为描述不足以明确要求时，指定具体方法
• 性能指导：内存限制、流式处理要求、批处理策略
• 特定语言的构造：泛型、注解、框架专用类型和惯用写法

不适用内容

• 行为和功能——应放在 ***functional specs*** 中
• 概念定义——应放在 ***definitions*** 中
• 符合性测试说明——应放在 ***test reqs*** 中。注意：单元测试说明应放在此处，而不是 ***test reqs*** 中——见下方的单元测试指导应放在此处。

单元测试指导应放在此处

所有关于 :UnitTests: 的内容都应放在 ***implementation reqs*** 中——包括路径、方法、软件包、框架（JUnit / pytest / Jest / Go 的 testing / …）、约定、测试夹具、模拟策略、文件布局、命名、lint / 静态分析门禁。单元测试属于生成的代码库，因此，塑造单元测试的要求按定义属于实现要求。

• 单元测试生成器只读取 ***implementation reqs***；放在 ***test reqs*** 中的任何 :UnitTests: 内容都会被静默忽略
• 每条 :UnitTests: 要求都应以预定义的 :UnitTests: 概念为依据来表述，以便一目了然地看出其所属部分
• ***test reqs*** 仅用于 :ConformanceTests:——参见 add-test-requirement

核心原则：如何构建 vs 构建什么

***implementation reqs*** 描述软件应如何构建。 ***functional specs*** 描述软件应实现什么功能。

如果要求描述的是可观察到的行为（端点、业务规则、面向用户的功能），则应放在功能规格中。如果描述的是内部结构、技术或编码指导，则应放在此处。

格式

实现要求应以项目符号的形式写在 ***implementation reqs*** 部分中：

***implementation reqs***

- :Implementation: should be in Python 3.12.

- :Implementation: should use pip for dependency management.

- :ReportExporter: writes a :CsvFile: with streaming writes, never holding the full dataset in memory.

在有助于明确要求时，引用已定义的 :Concepts:。非叶子部分中的实现要求适用于其所有子部分。

封装警告

requires 模块只能从其依赖项接收功能规格，无法接收实现要求。如果下游模块需要了解某些行为，则必须将该行为写入功能规格，而不是此处。

验证清单

• 描述如何构建，而不是要构建什么
• 所有引用的 :Concepts: 都已在 ***definitions*** 中定义
• 未重复文件或其导入内容中已有的指导
• 按 concise-specs.md 的要求精简：使用普通词语，不写理由，也不写已指定技术的标准行为
• 已放入 ***implementation reqs*** 部分
• 不包含应放在 ***functional specs*** 中的行为要求