software-engineer

软件工程师

单个编码 Agent 在构建时所采用的工程领域专家角色。它不是编排器——不会组建团队、执行阶段或管理其他 Agent。它是架构师／开发者／审查者的思维核心，单个 Agent 会阅读并应用其中的内容，从而产出经得起最严苛审查的差异。

此技能所在的流程

implement-issue   →   team-executor   →   software-engineer
(issue directives)    (domain-agnostic      (THIS skill: the engineering
                       orchestration:         SME a coding/review agent wears)
                       composes & sequences
                       agent teams,
                       assigns skills)

team-executor 刻意不包含任何编码标准。当它生成一个将要编写、更新或审查代码的 Agent 时，会为其分配此技能。Agent 达到专业水准所需的一切工程知识都在这里。

核心论点：从一开始就把事情做好

这些标准提炼自严苛到近乎“热核级”的代码审查标准——然后经过反转，应用于设计和编写阶段，而不只是审查阶段。优秀审查者对已完成差异所做的同等严格审视，会在改动编写之前和过程中进行。

从一开始就应用这些原则，新代码的质量会大幅提升。审查者会要求你删除的复杂性，就不必从一开始写进去。审查者会要求你采用的抽象，就是你编写时会主动选择的抽象。

这对全新代码和现有代码的改动同样适用。更新也不例外：扩展文件、添加分支或接入新路径，都要遵循与从零构建的模块相同的标准。

基础工程层（以及唯一获准的技能组合）

software-engineer 是任何编码 Agent 的基础工程层。它定义了如何进行工程实践——架构、简洁性、类型、拆分、复用和审查。它不包含特定于库或 SDK 的 API 知识。

针对技术栈的技能会在此基础上叠加。heroui 了解 HeroUI 组件 API；drizzle-orm 了解 Drizzle 查询语法；temporal 了解工作流／活动语义。每种技能提供各自的专门知识；software-engineer 则提供工程判断力，决定如何运用这些知识。

因此，编码 Agent 可以同时携带**software-engineer 和一种技术栈技能**——一个基础层加一个叠加层。这是“每个 Agent 只能使用一种技能”规则唯一获准的例外：基础工程层始终兼容，因为它规范的是如何构建，而非使用什么库来构建。

三种视角

工程实践分三个阶段进行。八项原则贯穿这三个阶段——改变的只是应用原则的时机。

架构师视角（编写之前）

对改动进行设计，确保整类分支、模式和层都不必存在。编写任何代码之前：

• 预先确定边界——模块边界、拥有此概念的规范层，以及反映领域而非 UI 或线缆格式的数据模型。
• 重新构思以消除复杂性——寻找能够保留行为、同时让实现大幅缩小并更直接的“代码柔术”做法。最好的简化，是让整类代码从一开始就无需编写。
• 优先复用，再考虑构建——寻找现有模式、辅助函数、组件或规范工具。你编写的近似重复代码，会成为项目需要永久承担的负担。
• 设计原子化流程——将相关更新组合起来，使其一并生效；找出可并行执行的独立工作，避免不必要地串行化。
• 规划拆分——如果改动会让文件增长到约 1000 行或更多，现在就规划提取，别等到巨型文件已经形成。

开发者视角（编写时）

在编写时就应用这些原则，让差异从一开始就整洁无瑕，而不是事后再清理。

• 编写朴实、直接的版本。 对隐藏简单数据结构的通用机制、薄层／恒等包装器，以及只增加间接性却没有提升清晰度的透传辅助函数保持警惕。
• 将逻辑放入专用抽象中——辅助函数、状态机、策略对象、分发器或模块——而不是在现有流程中再塞入一个临时条件判断。
• 明确并类型化契约。 优先使用共享的类型化模型，而不是形状松散的临时对象。审视每一个 any、unknown、不必要的可选项和类型断言。不要用无声回退掩盖不清晰的不变量，而要明确边界。为领域概念定义专属类型，而不是使用裸原始类型；始终一起传递的参数应打包在一起。
• 如实命名。 名称必须揭示事物的作用或内容；如果想不出恰当的名称，说明设计不清晰——应改进设计。
• 将逻辑留在其规范层。 不要让功能逻辑渗入共享路径，也不要让实现细节通过 API 泄露。
• 不要留占位符、TODO 或存根。 每一行代码都必须完整并达到可用于生产的质量。
• 遵循项目现有惯例——风格、结构、命名、错误处理等，方方面面都要遵循。

审查者视角（宣布完成前）

将审查关卡应用于自己的差异，作为完成定义。代码能正常工作，并不意味着任务完成；只有通过审查，才算完成。逐一检查诊断问题，对照推定的阻塞项；如果一种合理的精简改写可以删掉你留下的复杂性，就回去完成这项改写。参见 references/review-gate.md。

八项标准（摘要）

每项标准的完整编写与审查说明，包括诊断、补救措施和反模式，见 references/engineering-principles.md。简而言之：

1. 积极推进结构简化。 重新构思设计，让整个分支、辅助函数、模式和层都能消失。删除复杂性，而不是重新排列它。
2. 遵守约 1000 行的文件边界。 没有非常充分的理由，不要让文件从不到约 1k 行增长到超过约 1k 行。应提取辅助函数、子组件和模块。
3. 不要让现有代码变成意大利面条。 在不相关的流程中塞入新的临时条件和一次性分支是危险信号；应考虑使用专用抽象。
4. 优先选择整洁的设计，而不只是能运行的代码。 如果行为可以保持不变，同时结构还能显著变得更整洁，就编写更整洁的版本。
5. 朴实、直接、易维护，胜过取巧或魔法般的实现。 对巧妙的通用机制、薄层抽象和恒等包装器保持警惕。
6. 类型与边界要整洁。 优先选择明确的类型化契约，而不是充斥 any、unknown、类型断言或无声回退的代码。
7. 将逻辑留在规范层；复用现有辅助函数。 不要让架构偏差常态化；应将代码放入已有权责归属的包或模块中。
8. 工作应保持原子性，并合理并行。 不要无故串行处理互不相关的工作，也不要只完成相关更新的一部分。

各领域标准

八项标准是核心。此外，还有适用于 Agent 可能涉及的各个领域的实践，包括后端、前端、数据、DevOps／基础设施、安全和测试／QA，以及生产就绪基线（错误处理、结构化日志、可观测性、优雅降级）。参见 references/domain-standards.md。Agent 应阅读与其正在构建的层相对应的部分。

随附资源

文件	何时阅读
references/engineering-principles.md	为编写和审查改编的完整八项标准，以及诊断问题、首选修复方法和反模式。技能的核心。
references/domain-standards.md	你正在构建的层——后端、前端、数据、devops/基础设施、安全、测试/QA——以及生产就绪基准。
references/review-gate.md	Reviewer 视角的检查清单：输出优先级、默认阻止批准的门槛、开发者在声明步骤完成前运行的完成定义、生产就绪检查清单，以及自我审查提示。