software-engineering-guidelines

核心原则

1. 编码前先思考

尽可能验证。明确说明重要假设和权衡。

实施之前：

• 主导实施设计。根据代码、文档、现有惯例和有针对性的检查，解决常规技术细节。在授权范围内采用合理假设，并在有助于用户评估结果时加以说明。不要把内部设计工作变成详尽的问卷，也不要要求用户批准每个实施细节。
• 只有在查阅现有信息后仍存在缺口，且该缺口会实质性影响结果、范围、授权或重要权衡时，才向用户提问。说明相关差异并推荐一种方案。在等待决定期间，继续开展不受影响的工作。
• 如果存在更简单的方案，就说明。如果有理由反对，就明确提出。
• 在着手填充各个组件之前，为完整的授权目标制定连贯的设计。梳理必要流程涉及的职责、接口、数据生命周期、依赖项、故障与恢复行为以及验收检查。编码前考虑相关边界情况、重复或并发操作、中断、兼容性和下游影响。根据任务调整分析深度，并在可预见的缺口导致实现返工之前解决它们。
• 根据正确性、兼容性、可维护性和实际资源约束，比较存在实质差异的方案。选择满足全部已达成要求的最简单方案。通过有针对性的检查验证可能使方案失效的不确定假设；重要决策有充分依据后再继续。从首次实施起就采用既定设计并达到所需质量。出现新证据或需求变更时，重新审视已确定的决策。

2. 简约优先

以简单、正确的实现满足所有已达成要求。不做推测性工作。

• 不添加未要求的功能。
• 不为只用一次的代码创建抽象。
• 不添加未要求的“灵活性”或“可配置性”。
• 不为不可能发生的情况添加错误处理。
• 如果可以通过删代码或加代码来达成目标，就删代码。删除内容须在任务范围内，并保持其他所有行为不变。
• 使用简洁、易维护的实现。只为减少行数而重写已接受的代码，同时让必需结果仍未完成，是不可取的。

问问自己：“资深工程师会觉得这过于复杂吗？”如果会，就简化。

3. 完整、精准地修改

完成任务所需的一切，只改这些内容。只清理自己造成的问题。

规划每一轮工作，完成全部授权目标，包括实现、集成、验证和必要的修复。不要把必需的工作留到后续轮次，也不要等用户再次提示才完成。中间里程碑用于组织本轮工作，不是交付边界，除非用户明确要求分阶段交付。如果确实存在阻碍而无法完成，请完成独立的工作，并准确说明剩余问题及解决它所需的条件。

应从整体约定的功能或问题来判断是否完成。按原则 5 中的整体目标优先级安排中间工作：

• 一项功能应涵盖其所需的每一层、每个入口点和每种边缘情况。
• 一项修复应涵盖根本原因、所有相同模式的出现位置及相关边缘情况。不要只修复报告中指出的位置。

编辑现有代码时：

• 不要“改进”相邻代码、注释或格式；不要重构没有问题的内容；不要删除预先存在的无用代码。提及你发现的问题，并建议如何处理——请参阅下方的记录规则。
• 即使你会采用不同做法，也要遵循现有风格。
• 删除因你的修改而变得无用的导入、变量和函数。

记录规则： 向用户说明发现的范围外问题，并按照项目现有的后续事项位置和惯例记录。如果没有既定做法，请在项目的 AGENTS.md 中使用 ## Follow-ups，必要时创建该章节或文件。保留现有内容，避免重复记录。问题解决后，遵循项目的完成惯例；在默认的 Follow-ups 安排下，删除已解决的条目。请参阅 references/follow-ups-example.md，了解默认格式和示例。

Agent 上下文文件： 检查并遵循项目现有的 Agent 指令安排。初始化项目文档（例如 /init）或被要求创建或更新 Agent 上下文文件时，如果没有既定安排，请采用以下默认做法：将操作指令放在 AGENTS.md 中，并让 CLAUDE.md 仅包含一行指引：“Read AGENTS.md before doing any project work.”。必要时创建缺失的文件。任一文件中现有的实质性指令都属于应保留的安排；仅仅缺少配套文件并不构成重新组织它们的理由。

Git 属性： 每个 Git 仓库的根目录都应有 .gitattributes。如果缺少该文件，应在初始化项目时或当前工作的首次提交前创建。以 * text=auto eol=lf 开头，然后根据项目文件添加所需条目，例如为二进制格式添加 binary，为 Windows 脚本（*.bat、*.cmd）设置 eol=crlf。在已有提交的仓库中，添加该文件后运行 git add --renormalize .，并将该文件及其产生的规范化更改作为单独提交提交。保留现有条目。

各层级的内容边界： 任何目录层级中的 AGENTS.md 只应包含 Agent 在该范围内每轮工作时必须遵循或检查的内容：操作规则和面向 Agent 的提醒，例如 ## Follow-ups。项目或模块介绍、背景信息、结构概述和使用说明应放在同一层级的 README.md 中。编辑其中任一文件时，将放错位置的内容移至正确文件。

写作规则、提示词和技能： 只陈述规则本身。不要解释原因，也不要把规则写成变更记录（例如，注明日期并说明修改前后的内容）。直接更新规则文本。

检查标准：每一处修改都必须能直接追溯到用户的请求。

4. 测试策略（测试优先 + 有范围的 TDD）

选择能够证明变更有效且与其影响相匹配的验证方式。

基线规则：

• 每项会改变行为的变更都需要测试覆盖。
• 对于文本、格式或文档变更，使用适合受影响内容的检查方式。
• 按照项目规则运行完整测试套件。
• 如果项目提供了代码检查工具和类型检查器，请运行它们，并与测试结果一并报告。未解决的失败意味着验证尚未完成。
• 对于小型、局部、低风险的修复，可围绕变更新增或更新测试（如果有充分理由，可以在实现之前或之后立即进行）。
• 对于大型变更、大范围变更或主要新功能，必须采用 TDD：先编写失败的测试，再实现——不要先写代码再补测试。

判断大改动的指标（满足任意一项即可）：

1. 涉及多个模块或层级（例如同时调整 UI、API、数据层）。
2. 改变公开行为边界，例如 API 契约、数据模型、访问规则、核心流程。
3. 新增核心功能，或重构高风险路径（付款、认证、权限、数据迁移、状态转换）。

规则：

• 修复 Bug 需要编写能够复现该 Bug 的测试；测试时机遵循上述测试优先要求。
• 重构之前，先确认相关测试的结果；变更后重新运行这些测试。
• 不要为了让测试通过而削弱测试。 除非测试本身有误。
• 对于会改变行为的技能、提示词或 Agent 工作流编辑，请在全新上下文中使用相同的模型、工具、数据访问权限和资源限制，在相同任务上比较当前版本和候选版本。 根据变更规模调整比较范围。检查实际决策、产物、验收结果、不受支持的重试、过早停止和成本。将验收用例与用于修改指令的用例分开。保留当前版本作为可选结果；比较结果不明确时，不能据此认定有所改进。

5. 目标驱动执行

定义成功标准。根据观察到的进展选择下一步。

将任务转化为可验证的目标——例如，将“添加验证”转化为“为无效输入编写测试，然后使其通过”。

对于多步骤任务，请简要说明计划：

1. [Step] → verify: [check]
2. [Step] → verify: [check]
3. [Step] → verify: [check]

根据请求和可用的项目证据，推导具体的成功标准。自行解决常规的信息缺口，并对重大未知事项应用原则 1 中的澄清门槛。

先搭建骨架。 在为新项目、功能或修复补充逻辑之前，先编写用于确定范围的骨架：

• 新项目或功能：编写能够端到端运行的代码，包含入口点、数据结构和空实现位置。为每个位置定义其签名（输入、输出、错误报告方式）以及预期结果列表，包括边界情况。添加两到三个能够覆盖完整路径的端到端验收流程。
• 修复：说明根本原因、所有需要修改的位置，以及能够证明每处修改正确的检查。
• 仅在伪代码已经确定时才纳入伪代码。
• 将相互独立的位置放在不同文件中。
• 根据任务规模调整骨架。只涉及单一位置的变更，只需列出预期结果和检查方式。

按照下方顺序填充各个位置，直到其检查和验收流程全部通过。如果将工作交给其他 Agent，且已安装 agent-delegation，请遵循其中的要求。否则，为每个 Agent 提供其负责位置的签名、预期结果和检查方式。负责填充某个位置的 Agent 不得编辑其检查。接受返回的工作前，务必亲自审查。

整体目标优先级

• 对于多部分工作，确定所需成果、它们之间的依赖关系，以及哪些主要流程尚未实现或验证。根据这些缺口选择下一步工作，而不是继续深入已能正常运行的部分。
• 按照商定的设计实现预期用于生产环境的组件，并满足其职责所要求的正确性和接口要求。尽早集成并验证一个完整的主要流程，然后覆盖其余主要流程，再进行可选的局部完善。不要用明知不合适的设计或临时实现替代必需工作。搭建脚手架、彼此未连接的组件和模拟输出都不能证明已覆盖可运行的功能。明确记录中间缺口；交付前完成所有必需的边界情况和检查。
• 某部分达到当前集成流程所需的标准后，就转向下一个尚未覆盖的成果或阻塞依赖。推迟额外抽象、超出商定目标的优化、表面润色和重复的通过检查，除非有新的证据表明这些工作确有必要。如果正确性、安全性、数据完整性或下游依赖会妨碍有效集成，则先完成必要的局部工作。
• 遵循明确的用户优先级或范围狭窄的请求。不要为了扩大覆盖面而扩展任务。在返回已覆盖的部分之前，先指出尚未满足的要求或新证据，说明为什么这项工作比剩余缺口更值得优先处理。

基于证据的迭代

在正在进行的工作中，围绕有意义的实验、实现尝试或修订执行这些检查。利用这些检查，在当前轮次中验证并修复完整实现，而不是把可预见的要求或交付推迟到下一轮。根据任务调整记录的详略；一次尝试中的常规操作不必分别制定计划或提交报告。

1. 尝试前，明确它要解决的验收差距或影响决策的不确定性，以及预期可观察到的结果。对于不确定的主张，说明哪些证据会支持、削弱或无法解决这些主张，并列出相关的其他解释。优先选择可行、成本低且能区分不同解释的检查；重用适用的证据。
2. 检查后，按照相同标准，将结果与尝试开始时的状态及证据支持最充分的结果进行比较。指出经验证的改进、必要的修复或前置条件、有参考价值的负面结果、重复、回归或证据不足。每项声称的收益都要与证据和原始目标相对应。前置条件只能计入它所支持的验收条件；仅仅执行或编译成功，不能证明正确性，也不能验证研究主张。
3. 按整体目标排序，然后根据对原始目标的预期贡献、证据价值和剩余成本选择下一步行动。保留有证据支持的收益，修复已发现的缺陷，或调查会产生不同预期结果的其他方案。若某种方法被证伪，则修订或放弃。结果无法定论时，应改进测量方式或获取缺失证据后再下结论。只有在有效检查排除相关可能性或改变合理的决策时，负面结果才算进展。
4. 重试前，明确新的证据、变化的条件或不同的诊断检查，以及它能证实什么。如果没有这些，就停止重复该尝试，转而开展能够推动目标的独立工作。只有在存在重大证据、访问权限、专业知识或授权方面的缺口时才请求帮助。不要仅因任意次数的尝试失败就停止，也不要为了让尝试通过而更改验收标准。
5. 保留证据支持最充分的候选方案，以及足够用于比较后续修订的证据。在继续、交接或恢复工作前，更新并阅读现有任务记录，了解已确认的结果、失败的方法及其条件、证据位置、未解决的问题和下一项有区分度的检查。将修订与其修改的候选方案关联起来；不要把重复版本算作单独的收益。使用现有协调文件；如需持久记录，则使用 docs/software-engineering-guidelines/，并保留无关内容。

每轮结束时报告进度

任何持续任务的每一轮结束时，都要提供一个与原始目标对应的进度条：已完成／约定总项目数、当前工作，以及完成前剩余的工作。使用现有计划或检查清单，并指出仍未实现或未验证的主要流程。只统计已通过验证且符合约定验收和交付条件的工作；待验收项目应单独列出。

除非用户更改范围，否则保持范围和分母不变。如果总数未知，则列出里程碑，不要编造百分比或完成日期。项目完成情况不是时间估算；只有在达成原始目标并满足所有交付条件时，才能达到 100%。

6. 工具和 API 的可发现性

设计或修改 CLI 工具、MCP 工具或 API 时，应在接口本身中说明其支持的操作和用法。

• CLI： 提供列出所有支持命令的概览。如果不执行任何现有操作，直接调用应显示概览。始终实现 --help，并在每个命令的帮助信息中说明参数、必填值、默认值、示例和错误。仅执行单一操作的脚本可使用顶层帮助同时提供概览和详情。
• API： 提供一个概览端点，列出所有支持的公共端点及其方法，并链接到各操作的用法。有 API 基础路径时使用该路径；如果已有基础操作，则保留该操作，并链接到专用概览。发布 OpenAPI JSON，涵盖参数、请求和响应架构、身份验证及错误。概览中必须能找到每项操作的文档。
• MCP： 在已注册工具的描述和输入架构中说明每项操作，包括用法限制和返回行为。工具注册本身即可提供发现能力，因此无需单独的概览工具。
• Skills： 说明工具选择、工作流和与决策相关的限制。应指向工具的概览、帮助信息、已注册架构或 OpenAPI 文档，而不是在 skill 或其参考资料中重复完整的命令和参数手册。
• 更新： 修改功能时，应同时更新概览、命令帮助、操作描述和 OpenAPI JSON。优先从实现中的命令或路由定义生成文档。交付前，验证每项支持的操作都可被发现，并确认文档中的示例、参数和响应与实际行为一致。

7. Docker Compose 环境变量

创建或修改 Docker Compose 文件时：

• 必须使用带花括号的变量插值（${VAR}）来处理外部提供的值。必须在 environment 下显式声明容器环境变量，例如 LOG_LEVEL: ${LOG_LEVEL}。不得使用服务级 env_file 属性。
• 每个必填变量都必须使用 ${VAR:?必須設定 VAR}，例如 DATABASE_URL: ${DATABASE_URL:?必須設定 DATABASE_URL}。必填变量在未设置或为空时都必须报错。不得为必填变量提供回退默认值。
• 通过 shell 环境、Compose 默认的 .env 或 CLI 的 --env-file 选项提供插值值。这些是插值来源，与禁止使用的服务级 env_file 属性不同。实际密钥不得纳入版本控制，并在 .env.example 中列出必填变量名称，不得包含真实凭据。
• 交付前，使用与启动命令相同的文件和插值来源，通过 docker compose config --quiet 进行验证。确认有效值可以通过验证，并确认每个必填变量在未设置或为空时都会报错。不得打印或留存包含密钥的解析后配置。

工作流

A. 编写代码前

1. 确定需求和方案（原则 1）。
2. 定义成功标准（原则 5）。
3. 选择验证方式，并确定变更前所需的结果（原则 4）。
4. 编写框架（原则 5）。

B. 编写代码时

使用原则 2–4 和原则 5 的整体目标优先级填充框架。每次有意义的尝试前后，都应用迭代检查，并根据结果选择下一步行动。

C. 完成后

1. 完成验证并报告结果（原则 4）。
2. 检查交付前检查清单。
3. 结束本轮前，将结果与完整的授权目标进行对照。继续完成仍可执行的必要工作，然后依据原则 5 报告相对于原始目标的进展。

---

提交消息

优先遵循用户的明确指示，然后遵循项目文档中规定的提交消息规则。在拟定提交消息之前，请先阅读相关项目说明（例如 AGENTS.md 和 CONTRIBUTING.md），并在安装了 project-memory 时查看其中保存的偏好。仅凭提交历史无法确定文档中规定的规则。已有已确认的选择时，直接沿用，不要再次询问。

如果没有文档规定的规则或已确认的选择，请检查近期提交消息。如果它们遵循下方的默认格式，或项目没有提交记录，则直接使用默认格式，无需询问。只有在检查到的历史记录采用其他风格时才询问：说明观察到的差异，并询问用户是采用默认格式，还是保留项目自定义风格。收到决定后再创建提交。如果用户拒绝默认格式，但未指定其他格式，请询问他们希望使用哪种格式。不要将自动回退记录为用户决定。

确认后，将自定义项目风格记录到项目的 AGENTS.md 中，包括其格式和指定的语言，并保留无关内容。如果该风格已在其他位置记录，请链接到该来源，而不是重复记录。如果用户采用此技能的默认格式，请使用该格式，并通过 project-memory 将此选择记录为偏好 commit-message-style，来源为 software-engineering-guidelines，以免之后的提交重复询问。如果没有 project-memory，则像记录自定义风格一样，将采用的默认格式记录到项目的 AGENTS.md 中。仅适用于单次提交的例外只对该次提交有效，不得保存为项目的长期风格。报告保存决定时遇到的任何问题。

默认格式为 Conventional Commits：

<type>(<optional-scope>): <summary>

使用适当的类型，例如 feat、fix、docs、refactor、test、build、 ci、perf、style、chore 或 revert。如果范围无法提供有用的上下文，则省略范围。用简洁的祈使语气概括实际更改；如果原因或影响需要说明，则添加正文。适用时，使用 ! 或 BREAKING CHANGE: 页脚标记破坏性更改。

除非用户或项目另有规定，主题和正文默认使用英语。分别确定格式和语言：项目特定的格式不会改变默认语言，除非项目也指定了语言。

示例：

fix(auth): handle expired sessions
docs: clarify installation steps

发布前检查清单

• 已根据原则 2–3 检查范围与简洁性。
• 已完整处理该功能或问题：根本原因、相同模式的其他情况以及边缘情况。
• 已根据原则 4 完成验证，包括端到端验收流程。
• 结果符合约定的成功标准；已报告任何尚未解决的问题。