xy-development

开发规范

权威来源。 此技能仅在 ariestools/ariestools-skills 中维护。XYOracleNetwork/xyo-skills 下的副本是重定向存根——请在此处编辑，切勿在那里编辑。

技能标识。 提交计划、确认或完成摘要时，请注明为其提供依据的技能，格式为 xy-development v<version>，并以相同格式列出此技能包中其他所有已启用的技能。版本号请从本文件的 metadata.version 中读取，切勿使用示例中的版本号。

此技能定义了基础开发实践。如果仓库自身的 AGENTS.md 或 CLAUDE.md 有不同规定，以仓库规定为准。请根据当前任务加载相应的子主题：

架构决策。 在更改引入分布式工作者职责、恢复规则或新的协调权限之前，请在可用时参阅 ariestools-architecture。优先采用由协议定义、可自主运行且可替换的工作者，并要求其具备持久化证据和安全的并发效果；如需协调，应根据不变量或资源约束说明理由。日常维护中应保留已接受的架构。工作流介绍了此范围内的审查，包括架构技能不可用时的处理方式。

目录

TypeScript 约定

编写、审查或重构 TypeScript 代码，或整理导入时阅读。内容涵盖严格性标记和代码结构限制；any 政策；返回类型；interface 与 type 的区别；readonly 的用法；可擦除语法规则（不使用枚举、参数属性或命名空间）；仅使用 ESM 模块并显式指定导入扩展名；根 barrel 导入和导入风格；条件、空值合并和 Promise；以及命名、导出和文件约定。

Git 工作流

提交、创建分支、推送、合并或创建 PR，撤销更改、解决推送被拒问题或发布版本时阅读。内容涵盖约定式提交和 PR 标题、原子提交、提交者身份和仓库卫生、重写历史的政策、分支模型检测、合并方式及版本发布。

测试原则

编写测试、讨论测试策略或评估覆盖率时阅读。内容涵盖与框架无关的原则：以行为为重点的名称、准备/执行/断言、每个测试验证一个概念、测试公共接口、保持测试独立且具有确定性、在仍能测试实际连接关系的前提下尽量减少模拟，以及覆盖率优先级。框架、运行器和测试文件布局由 xy-toolchain 技能定义（xy-toolchain 测试）。

开发工作流

运行任何构建、lint、测试或开发命令之前，添加或升级依赖之前，编写 PRD.md 的验收标准时，以及声明任务完成之前阅读。内容涵盖工具链发现（先查阅仓库说明、脚本和 CI，再考虑临时的一次性方案）、依赖和 peer 依赖规则、凭据安全、分层完成定义（包括应用的浏览器验证），以及编写项目专属的验收标准。

保留行为的重构

在文件或包之间移动代码、拆分或合并包、打破依赖环，或审查单体仓库的包图以评估内聚性和耦合性时阅读。内容涵盖行为不变原则；首次更改前运行基线；内聚性和耦合性发现及其默认严重程度和所有者审批步骤；跨包迁移的步骤（测试、入口点、导入位置、清单、路径别名）；已发布包的破坏性更改；以及每次迁移的验证规则。

相关技能

这些是导航链接，不是此技能的依赖项；每项都需要单独安装。

• ariestools-architecture — 关于自主性、权限、并发和恢复的通用设计偏好与评审标准。在架构决策时查阅；在已接受的设计范围内进行常规实现，不会重新开启这些决策。
• xy-toolchain — xy CLI、构建／lint／测试命令，以及这些原则所依托的工具。安装：npx skills add ariestools/ariestools-skills --skill xy-toolchain。
• ariestools-sdk — 应使用哪些 @ariestools/* 实用工具，以及如何导入。当仓库依赖 sdk-js 包时请查阅；xy skills lint 仅在这种情况下需要它，因此其他仓库通常没有此技能。安装：npx skills add ariestools/ariestools-skills --skill ariestools-sdk。
• ariestools-sdk-react — 哪个 @ariestools/sdk-react* 包负责某个组件或钩子、它的对等依赖，以及用于确保每个 React 上下文只有一个副本的导入规则。当仓库依赖 sdk-react 包时请查阅；从 toolchain 10.1.4 起，xy skills lint 仅在这种情况下需要它。安装：npx skills add ariestools/ariestools-skills --skill ariestools-sdk-react。
• ariestools-actor — 由 cli-kit 或 browser-kit 承载的 actor-kit actors、providers 和 actor 引擎。当仓库依赖 actor-kit、cli-kit 或 browser-kit 包时请查阅；从 toolchain 10.1.4 起，xy skills lint 仅在这种情况下需要它。安装：npx skills add ariestools/ariestools-skills --skill ariestools-actor。
• xy-agent — 建议安装，但非必需。 仓库文档约定：AGENTS.md 入口文件、各工具适配器，以及 docs/ 和 papers/ 的生命周期。在编写或重组面向 Agent 的仓库文档时，或仓库已遵循此模式时，请查阅；否则遵循仓库现有的约定。在 @ariestools/toolchain 仓库中，xy agent lint（自 toolchain 10.1.1 起）会强制执行该约定。自 10.1.2 起，pnpm xy check 仅在仓库存在根目录 AGENTS.md 或声明了 commands.agentLint（即使仅用于设置规则级别）时运行此检查；默认情况下，只有缺少根目录 AGENTS.md，或其中指向不存在目标的相对 Markdown 链接，才会报错。其他不符合项，例如未以 @AGENTS.md 导入语句开头的 CLAUDE.md，或缺少必需的 AGENTS.md 章节，会发出警告；只有在使用 --strict 或 XY_STRICT=1 时才会导致失败。Toolchain 10.1.1 会在每个仓库中运行此检查，并包含更多错误级规则（版本说明）。有关规则和 commands.agentLint.rules，请参阅 xy-toolchain › xy agent。pnpm xy agent init 会搭建此约定所需的文件，不会覆盖现有文件。安装：npx skills add ariestools/ariestools-skills --skill xy-agent；或者从 toolchain 10.1.2 起，使用 pnpm xy skills pick --skill xy-agent，该命令还会将其记录为必需技能，以便 pnpm xy skills lint 检查版本，并由 --fix 安装或更新它。自 10.1.2 起，xy repo init --skills-optional 也会在新仓库中安装此技能，只要技能层级不是 none；不过，该标志的帮助文本仍仅提及 XL1 技能。其他安装方式及其注意事项，请参阅 xy-toolchain › xy skills。