developing-agent-forge 2.3.2 → 2.5.0

package/metaskills/coding-style/METASKILL.md

@@ -1,214 +0,0 @@
-这个skill是通用代码风格与可读性skill，适用于任何repo、任何语言、任何框架和任何写代码任务。
-它只定义agent在写代码、改代码、补测试、重构、整理模块或修改文档时，怎样让代码简洁、规整、可读、可审阅、低耦合、易维护。
-上游任务决定“要实现什么”；本skill决定“代码应该怎样写得清楚、局部、低耦合、易审阅”。
-本skill不决定项目结构，不规定固定目录，不绑定具体领域流程，不替上游任务决定业务需求。
-
-这些原则与常见工程实践一致：code review的目标是持续改善code health；代码应符合语言和代码库的最佳实践；软件职责应按关注点分离；过长函数、过大类、长参数列表、重复代码和职责混杂都是需要警惕的code smells。
-
-## 总原则
-
-**General readable-code principle**：任何代码写作任务都应优先产出简洁、规整、可读、可审阅、低耦合、易维护的代码。
-**Project-agnostic principle**：skill只包含通用代码质量规则，不包含具体项目路径、目录结构、类名、函数名、语言生态或任务领域信息。
-**Reviewability principle**：代码应让审阅者容易看懂改动意图、影响范围和验证方式；相近功能应保持相近形状，差异点应集中且清楚。
-**Local-change principle**：每个功能应尽量在小范围内实现和修改；如果改动扩散到多个无关区域，应优先整理边界。
-**Balanced modularity principle**：模块拆分应服务高内聚、低耦合和可读性；既避免长文件和职责混杂，也避免过度拆分和无意义wrapper。
-
-## Project-agnostic skill hygiene
-
-skill本身必须保持项目无关，只沉淀跨项目稳定成立的代码质量原则。
-skill中不应写入具体项目名、仓库名、路径、目录、类名、函数名、模块名、配置名、任务名、数据集名、输出字段名或某次运行结果。
-具体命名、路径、组织方式、测试位置和文档位置，只能来自当次任务、当前repo和已有代码风格。
-skill可以使用抽象表达，例如“当前模块”“当前功能”“当前repo”“同类实现”“相关测试”，但不应把这些表达落成固定模板。
-如果某条规则换一个repo就不成立，说明它不应写进这个通用skill。
-如果某条规则包含某次任务产生的真实路径、符号、目录结构或输出结构，应删除或改写成抽象原则。
-skill不应通过硬编码项目细节来“帮助下次运行”；下次运行需要的项目事实应从当前repo和用户当前任务中重新获得。
-
-## 通用代码写作原则
-
-agent写代码时应优先保证代码清晰、直接、可读，而不是为了显得“工程化”引入不必要抽象。
-代码应短、直、少层级；能简化就简化，能直接表达就不要绕一层。
-代码应让数据流一眼可见：输入从哪里来，如何被处理，传给哪里，输出什么，应尽量顺着代码结构直接读出来。
-代码不应比必要更复杂；如果一个实现已经能清楚表达需求，不应再包装一层来制造架构感。
-命名应语义明确，使函数、变量、类、模块、测试、配置项和输出对象的用途尽量从名称中直接看出来。
-每个函数、类、模块和文件应有清晰职责；如果一个单元承担多个不相关职责，应拆分。
-复杂逻辑应拆成可理解的子功能，每个子功能有明确输入、输出和边界。
-避免过长函数、过大类、过重文件、长参数列表、重复代码和职责混杂的模块；这些都是应触发重构判断的信号。
-代码应贴近当前repo已有模式，但不要复制已有代码中的坏抽象、坏命名和历史包袱。
-遇到复杂代码时，优先判断哪些结构可以删除、内联、移动到使用点、重新命名或拆成更自然的子模块。
-
-## 命名、顺序和边界
-
-命名必须精确反映真实含义，不使用泛化、含糊、历史残留或与数据形态不一致的名称。
-名称应来自当前领域契约、用户输入和当前代码语义，而不是来自临时实现细节。
-名称应尽量短而语义完整，删除不增加信息量的前缀、后缀和包装词。
-同一个概念在接口、配置、类型、文案、文档、调用点和输出对象中应使用一致名称。
-改名时应同步相关调用点、测试和文档，避免旧概念残留在变量、接口、配置、提示文本或说明中。
-名称应清楚区分“内容本身”和“对内容的引用”。
-如果传递的是内容，就使用内容语义的命名；如果传递的是引用、位置、句柄或标识，就使用引用语义的命名。
-代码排列顺序应帮助读者理解流程；执行顺序明确的逻辑，应让代码顺序尽量反映执行顺序。
-输入、校验、构造、调用、输出等步骤应按自然阅读顺序组织。
-语义对应的结构应尽量保持字段顺序、参数顺序和定义顺序一致，减少读者在多个结构之间反复做脑内映射。
-相关代码应靠近放置，减少跨文件、跨模块、跨层级跳转。
-结构本身应表达意图，而不是依赖大量注释解释绕来绕去的数据流。
-
-## 抽象与接口
-
-抽象应来自真实重复、真实变化点或真实边界，不应为了预留未来可能性而过早引入。
-好的接口应让调用方代码更短、更清楚、更稳定。
-只有真正复用、表达稳定不变量、定义清晰边界、隔离变化点或显著提升局部可读性时，才抽成独立helper、接口、adapter、registry或runner。
-不要创建只负责转手、改名、包装、拆包或重新组装数据的helper。
-不要创建“拆开又合上”的中间结构；如果数据最终仍作为整体使用，应保留直接的数据流。
-如果接口要求调用方传入过多参数，应考虑是否需要更清晰的数据结构或上下文对象。
-如果配置系统让简单任务必须写大量配置，应考虑更轻量的默认值、局部覆盖或直接参数。
-如果新增一个功能需要修改多个注册点、多个wrapper、多个配置块，说明抽象可能太重或边界不清。
-如果某个抽象只是把复杂度从模块内部转移到每个调用方，应简化。
-如果某个模块拆分会导致大量跨模块转发函数、薄wrapper或只调用一次的抽象层，应合并或简化。
-抽象只有在减少重复、稳定边界、提升测试性、隔离变化或缩短调用方代码时才值得保留。
-
-## Change locality和高内聚低耦合
-
-每个具体功能的新增、替换或修改，都应尽量限定在语义明确的小范围内。
-写代码前应先判断当前功能主要属于哪个局部区域、哪个模块边界或哪个扩展点。
-如果一个功能需要同时修改多个无关区域，应先审视模块边界，而不是把改动直接散落到各处。
-需要一起变化的代码应放近；不因同一原因变化的代码应分开。
-模块之间应通过稳定接口、明确数据结构或显式契约协作，避免调用方依赖被调用方内部实现。
-修改某个模块内部实现时，其他模块不应因为内部细节变化而连锁修改；这是封装和低耦合的核心价值。
-如果某个模块因为多种互不相关原因频繁变化，应拆分职责。
-如果某个共享工具层开始混入业务逻辑，应把业务逻辑移回更具体的功能模块。
-如果当前功能无法局部实现，agent应指出边界或耦合风险，并优先做最小必要的局部重构。
-
-## 文件长度 / 模块粒度 / 子功能拆分
-
-不应生成过长、过重、职责混杂的文件。
-文件是否过长不是单纯行数问题，而是看它是否承载多个职责、多个变化原因、多个抽象层级或多个执行流程。
-复杂功能应先拆成子功能，再映射到清晰模块或文件。
-每个文件应有明确主题；如果一个文件同时包含输入解析、核心逻辑、外部调用、结果处理、错误处理和测试支持，应考虑拆分。
-拆分应服务可读性和局部修改能力，不应制造大量空壳文件、薄wrapper或纯转发层。
-如果多个文件之间出现大量只调用一次的间接层，应考虑合并或简化。
-避免“god file”“mega runner”“misc helpers”“all-in-one utils”这类低内聚结构。
-通用工具文件只应包含稳定、窄职责、确实被多处复用的代码。
-公共层只放真正公共、稳定、跨多个地方共享的内容。
-只在局部使用的helper、数据结构、配置、状态或特殊逻辑应放在使用点附近。
-共享基础结构只承载所有使用方共同需要的能力，不承载少数使用方的特殊逻辑。
-特殊case应尽量留在特殊case的使用位置，不要为了少数情况污染公共层。
-
-## 可审阅性原则
-
-写代码时要考虑reviewer的阅读路径：代码应让审阅者快速看出“改了什么、为什么改、影响哪里、如何验证”。
-功能相近的代码应尽量保持相近的文件组织、代码骨架、命名节奏、函数顺序和测试结构。
-如果一组实现大部分逻辑相同、只有核心算法或策略不同，应让公共骨架保持一致，把真正变化的部分集中在小范围内。
-不要机械消除所有重复；少量平行但形状一致的代码，有时比过度抽象更容易审阅。
-如果重复代码表达的是稳定公共骨架，并且抽象后能缩短调用方代码、减少维护点、提升一致性，可以提取共享逻辑。
-如果抽象会让调用链更长、理解成本更高、每个新增功能都要写更多样板代码，应保留更直接的实现方式。
-新增同类功能时，应先查看当前repo中已有同类实现，沿用其清晰结构，而不是创造新的局部风格。
-如果已有同类实现风格不一致，新增代码时应优先选择最清晰、最符合当前repo的一种形状，并在任务范围允许时做局部整理。
-严格遵循格式不只是通过formatter，也包括沿用同类代码的执行顺序、操作位置、直接调用方式和数据处理边界。
-初始化、目录准备、资源创建等前置操作应出现在拥有该流程的开头位置，不应藏进后续写入、保存或调用helper里。
-抽出同类流程时，应保留原流程中局部执行配置的归属；如果同类函数在函数开头本地创建回调、logger、formatter或执行上下文，新函数也应在相同位置本地创建，而不是把它提升成options参数。
-options只应承载调用方真实决定的输入；不要为了跨函数转发方便，把局部实现细节、临时执行工具或可在被调用流程内自然创建的对象放进options。
-如果某个对象被定义成可独立调用的命令、pipeline、task或entrypoint，它的参数定义必须完整描述独立调用所需的外部输入；不要留下空参数定义再依赖程序内调用方传入内部结构。
-命令入口应负责把外部字符串、路径和配置解析成内部结构；核心函数应接收已经准备好的领域输入，二者边界应清楚，避免把内部对象模型暴露成命令行契约。
-如果子流程并不自然适合作为独立命令或entrypoint，不应为了“拆分”强行包装成pipeline、CLI或注册入口；应使用普通函数、机制类或facade类表达内部编排。
-当调用方已经拥有内容本身时，被调用的内部机制应接收内容字符串，而不是重新要求文件路径；路径读取属于外部入口或拥有IO责任的流程。
-写入、保存、发送等副作用应尽量在产生内容的流程附近直接表达；不要为了少量调用创建只转发API的helper。
-除非当前需求或既有代码明确要求，写入内容时不应顺手做trim、补换行、重新格式化等隐式字符串处理。
-任何内容转换都应在代码中有清楚的语义位置，让审阅者能直接看出内容是在何处产生、何处被改变、何处被保存。
-
-## 状态、内容和引用
-
-每个变量、状态、配置和数据结构都应属于真实拥有它的层级。
-局部流程中产生的内容应留在局部，不要提升成公共状态或共享输入。
-只有长期稳定、跨边界仍有语义的数据才进入共享结构。
-临时状态不应被建模成长期状态；中断、重启、重跑后语义不稳定的概念不应成为核心模型。
-单次流程中的中间内容应优先作为值直接传递，不要为了保存而改变数据模型。
-上层派生并只由上层使用的内容应留在上层，不应伪装成下层模块的输入。
-如果某个数据只服务于编排、保存或展示，不应污染业务模块的接口。
-层级边界应清楚：谁负责生成、谁负责处理、谁负责保存、谁负责暴露，都应在代码结构中直接体现。
-当外层负责保存、归档或落盘时，内层不应同时承担同一写入责任。
-写入、保存、导出、返回等责任应单一，避免多个层级同时声称负责同一个产物。
-
-## 测试相关的通用原则
-
-测试路径不由本skill固定；新增测试应遵守当前repo已有测试布局和命名风格。
-测试应验证明确行为，有清晰pass/fail标准。
-测试应尽量小而具体，使失败原因容易定位。
-测试代码本身也应保持可读、局部、命名清楚，不应成为难以维护的脚本堆。
-同类测试应保持相近结构和相近断言风格，降低审阅成本。
-当修改核心逻辑时，应补充或更新能覆盖该行为的测试；具体测试框架和路径由当前repo决定。
-测试应覆盖本次改动的公共行为、边界条件和关键错误路径，不应为了覆盖率而复制大量低价值断言。
-测试fixture应小、稳定、能说明行为；不要让测试依赖无关的大型输入或难以解释的历史数据。
-如果重构不应改变行为，应优先保留或补充能证明行为保持一致的测试。
-
-## 文档相关的通用原则
-
-这个skill不固定任何文档文件名。
-如果当前任务改变了公共接口、模块边界、使用方式、配置方式或重要行为，应同步更新当前repo已有的相关文档。
-文档应描述当前代码实际行为，不应保留过时结构或模板化说明。
-文档应帮助后续开发者理解如何使用、扩展或修改代码，而不是解释agent内部流程。
-如果当前repo有架构说明、开发者说明或使用说明，应保持这些文档与代码一致；文件名和位置遵守当前repo约定。
-文档中的名称、顺序、边界和行为描述应与代码、测试和配置保持一致。
-不要把风格分析、实现过程、工具调用细节或skill规则写进项目文档。
-
-## Prompt和注释
-
-如果repo中包含prompt、任务说明、内嵌文案或给agent的指令文本，这些文本也应遵守代码风格。
-内嵌任务说明应直接描述任务，不使用角色扮演式开头。
-输入说明应清楚区分外部引用和直接内容。
-输出说明应明确谁负责生成内容、谁负责保存内容，避免让执行者误解写入责任。
-不要在内嵌文本中使用没有上下文的裸文件名、伪路径或模糊指代。
-如果一段文案会误导执行者产生错误行为，应改成直接描述真实责任。
-Prompt文本应短、明确、任务导向，不展示skill内部流程。
-注释只用于解释非显然决策、约束、边界条件、来源或特殊原因。
-不要用注释掩盖糟糕结构；优先通过更好的命名、更清晰的拆分和更直接的数据流让代码自解释。
-不要用注释解释本可以通过命名、结构或边界表达清楚的内容。
-不要把风格分析、实现过程、调试过程或skill规则写进代码注释。
-注释应服务后续维护者理解代码，不服务展示生成过程。
-
-## Readability audit
-
-每次写完或修改代码后，agent应做一次readability audit。
-readability audit应检查命名是否清楚、函数是否过长、文件是否过重、模块职责是否单一、抽象是否必要、调用链是否过绕。
-readability audit应检查新增代码是否符合当前repo已有风格。
-readability audit应检查当前功能是否主要限定在小范围内。
-readability audit应检查是否存在重复注册点、长参数列表、薄wrapper、过度拆分、隐藏全局状态或复杂配置负担。
-readability audit应检查相近功能是否保持相近代码形状，差异点是否集中且容易审阅。
-readability audit应检查测试是否局部、明确、可读，并遵守当前repo已有测试风格。
-readability audit应检查相关文档是否需要随公共接口、模块边界、使用方式或重要行为变化而更新。
-如果代码能工作但不够清楚，应优先重构为更清晰的形式。
-如果发现为了“可扩展”而加入当前任务不需要的抽象，应删除或简化。
-如果发现某个函数、文件或模块的名称不能解释其用途，应重新命名或重新拆分。
-如果发现改动扩散到多个无关区域，应优先整理边界或说明耦合风险。
-编写或更新skill时，应做一次project leakage audit，检查是否混入项目名、路径、类名、函数名、模块名、任务名、数据集名、输出字段名或某次运行输出。
-project leakage audit发现具体项目内容时，应优先改写成抽象原则；无法抽象的内容应删除。
-
-## 代码审阅
-
-审阅代码时优先检查是否存在无意义抽象、过度函数化、错误层级归属、命名不精确、状态不稳定、顺序不一致、数据流不清晰、文件过重、模块边界混乱和change locality差。
-审阅建议应优先指向删除、内联、移动到使用点、统一命名、对齐顺序、拆分职责和澄清边界。
-不默认建议增加更多抽象、更多配置层、更多wrapper或更多defensive处理。
-如果代码已经足够直接，审阅应避免提出“为了整洁再抽一层”的建议。
-如果发现变量属于错误层级，应建议把它移回真实拥有者所在层，而不是通过新类型或适配函数绕过去。
-如果内容和引用混用，应要求通过命名和数据流区分真实语义。
-如果临时状态被写进长期模型，应要求改成稳定概念或移回局部流程。
-如果旧概念残留在名称、文案、配置或接口中，应要求清理残留并统一契约。
-如果某个功能修改牵动多个无关模块，应指出耦合风险，并建议更清楚的局部边界。
-
-## Scope hygiene
-
-这个skill只关注代码风格、可读性、可审阅性、模块粒度、低耦合、高内聚和局部修改能力。
-这个skill不包含运行环境问题、工具失败处理、文件读取fallback、沙盒限制或orchestrator逻辑。
-这个skill不包含外部调研流程、高质量公开库搜索、语言生态现场分析、开源代码下载或工具选型流程。
-这个skill不包含领域任务逻辑、固定目录、固定文档文件、固定测试路径或固定repo骨架。
-这个skill不替上游任务决定业务需求；它只约束代码实现质量。
-当上游任务只要求一个小功能时，本skill不应扩大任务范围重构整个repo；它应在小范围内保持代码清楚。
-当上游任务需要新增目录、模块或文件时，新增结构应来自当前repo和当前功能的自然边界，而不是来自本skill预设。
-如果上游任务和本skill发生边界冲突，应优先完成用户当前任务，并把代码质量整理限定在必要范围内。
-
-## 输出要求
-
-输出应聚焦代码修改本身和必要说明。
-不输出skill内部流程、风格分析过程或工具使用细节。
-不把“我是根据某条skill规则这样写的”这类元信息写给用户。
-不在代码注释中解释风格规则。
-修改说明应短，直接说明改了什么、为什么这样改，以及是否还有与代码本身相关的注意点。
-不写过多背景解释，不把简单修改包装成复杂设计说明。