xy-development
Compare original and translation side by side
🇺🇸
Original
English🇨🇳
Translation
ChineseDevelopment Standards
开发标准
Authority. This skill is maintained only in . Copies under are redirect stubs — edit here, never there.
ariestools/ariestools-skillsXYOracleNetwork/xyo-skillsSkill identity. When you present a plan, an acknowledgement, or a completion summary, state which skills informed it as , and list each other active skill from this pack the same way. Read the version from this file's , never from an example.
xy-development v<version>metadata.versionThis skill defines foundational development practices. Where a repository's own or says otherwise, the repository wins. Load the sub-topic that matches your current task:
AGENTS.mdCLAUDE.mdArchitecture decisions. Before a change introduces distributed worker responsibilities, recovery rules, or new coordination authority, consult ariestools-architecture when available. Prefer protocol-defined autonomous, replaceable workers with durable evidence and safe concurrent effects; justify coordination by its invariant or resource constraint. Preserve the accepted architecture during routine maintenance. The workflow describes this scoped review, including when the architecture skill is absent.
权威来源。 此 skill 仅在 中维护。 下的副本均为重定向占位文件——请在此处编辑,切勿在那些副本中编辑。
ariestools/ariestools-skillsXYOracleNetwork/xyo-skillsSkill 身份。 当你提交计划、确认说明或完成总结时,应说明哪些 skill 为其提供了依据,格式为 ,并以相同方式列出本 skill 包中的每个其他活动 skill。始终从此文件的 读取版本,绝不要从示例中读取。
xy-development v<version>metadata.version此 skill 定义了基础开发实践。如果仓库自身的 或 另有规定,则以仓库规定为准。加载与当前任务匹配的子主题:
AGENTS.mdCLAUDE.md架构决策。 在某项变更引入分布式 worker 职责、恢复规则或新的协调权限之前,如存在相关 skill,请查阅 ariestools-architecture。优先采用协议定义的自主、可替换 worker,并为其提供持久化证据与安全的并发副作用;必须以相关不变量或资源约束为依据,说明采用协调机制的合理性。在日常维护中保持已认可的架构不变。工作流 介绍了这种限定范围的审查,包括架构 skill 不可用时的处理方式。
Table of Contents
目录
TypeScript Conventions
TypeScript 规范
Read when writing, reviewing, or refactoring TypeScript code, or organizing imports. Covers strictness markers and code-shape limits; the policy; return types; interface vs type; readonly usage; erasable-syntax rules (no enums, parameter properties, or namespaces); ESM-only modules with explicit import extensions; root-barrel imports and import style; conditions, nullish values, and promises; and naming, export, and file conventions.
any编写、审查或重构 TypeScript 代码,或整理 import 时阅读。涵盖严格性标记和代码形态限制; 策略;返回类型;interface 与 type 的区别;readonly 用法;可擦除语法规则(禁止 enum、参数属性或 namespace);仅支持 ESM 的模块与显式 import 扩展名;根 barrel import 与 import 风格;条件、nullish 值和 Promise;以及命名、导出和文件约定。
anyGit Workflow
Git 工作流
Read when committing, branching, pushing, merging or opening PRs, undoing a change, resolving a rejected push, or cutting a release. Covers conventional commits and PR titles, atomic commits, commit identity and repository hygiene, the history-rewrite policy (shared branches stay append-only; an unpushed topic branch changes only when the user asks), working in the checkout you were given, branching-model detection from or , merge methods, and releases.
AGENTS.mdorigin/develop提交、分支、推送、合并或创建 PR,撤销变更,处理被拒绝的推送,或发布版本时阅读。涵盖 conventional commit 和 PR 标题、原子提交、提交身份与仓库整洁性、历史重写策略(共享分支保持仅追加;未推送的主题分支仅在用户要求时改写)、在分配给你的 checkout 中工作、根据 或 检测分支模型、合并方式以及发布流程。
AGENTS.mdorigin/developDeployment Conventions
部署规范
Read when creating, changing, simplifying, or migrating deployment workflows or provider branch mappings. Covers names, native Vercel versus CI prebuilt/image delivery, one automatic build/deploy path, explicit approval for naming exceptions, homelab scope, and compatibility across independently deployed components.
<environment>[-<component>]-<target>[-<build-mode>]创建、修改、简化或迁移部署工作流或 provider 分支映射时阅读。涵盖 命名规则、原生 Vercel 与 CI 预构建/镜像交付、仅保留一条自动构建/部署路径、命名例外需明确批准、homelab 适用范围,以及独立部署组件之间的兼容性。
<environment>[-<component>]-<target>[-<build-mode>]Testing Principles
测试原则
Read when writing tests, discussing test strategy, or evaluating coverage. Covers framework-agnostic principles: behavior-focused names, arrange/act/assert, one concept per test, testing the public interface, independent and deterministic tests, minimal mocking that still leaves the real wiring tested, and coverage priorities. Frameworks, runners, and spec layout are defined in the xy-toolchain skill (xy-toolchain testing).
编写测试、讨论测试策略或评估覆盖率时阅读。涵盖与框架无关的原则:以行为为中心的命名、arrange/act/assert、每个测试只验证一个概念、测试公共接口、独立且确定性的测试、在确保真实连接逻辑仍得到测试的前提下尽量减少 mock,以及覆盖率优先级。测试框架、运行器和 spec 布局由 xy-toolchain skill 定义(xy-toolchain 测试)。
Development Workflow
开发工作流
Read before running any build, lint, test, or dev command; before adding or upgrading dependencies; when writing a PRD.md's acceptance criteria; and before declaring any task complete. Covers toolchain discovery (repo instructions, scripts, and CI before ad-hoc one-offs), dependency and peer-dependency rules, credential safety, the layered Definition of Done (the toolchain completion gate is scoped and , with only for policy and document edits, plus browser verification for apps), and writing project-specific acceptance criteria.
xy buildxy testxy check运行任何 build、lint、test 或 dev 命令之前,添加或升级依赖之前,编写 PRD.md 的验收标准之前,以及宣布任何任务完成之前阅读。涵盖工具链发现(先从仓库说明、scripts 和 CI 中发现工具链,而不是临时执行零散命令)、依赖和 peer dependency 规则、凭据安全、分层的完成定义(toolchain 完成门禁限定为 和 , 仅用于策略和文档编辑,应用还需进行浏览器验证),以及编写项目特定的验收标准。
xy buildxy testxy checkBehavior-Preserving Refactors
保持行为不变的重构
Read when moving code between files or packages, splitting or merging packages, breaking dependency cycles, or auditing a monorepo's package graph for cohesion and coupling. Covers the no-behavior-change invariant; a baseline run before the first change; cohesion and coupling findings, their default severities, and the owner-approval step; the steps of a cross-package move (tests, entry points, import sites, manifests, path aliases); breaking changes for published packages; and the per-move verification rule.
在文件或包之间移动代码、拆分或合并包、打破依赖循环,或审计 monorepo 包图的内聚性与耦合性时阅读。涵盖不改变行为这一不变量;首次变更前运行基线;内聚性与耦合性问题、默认严重级别及所有者批准步骤;跨包迁移的步骤(测试、入口点、import 使用点、manifest 文件、路径别名);已发布包的破坏性变更;以及每次迁移的验证规则。
Related skills
相关 skill
These are navigation links, not dependencies of this skill; each installs separately.
- ariestools-architecture — the shared design preference and review criteria for autonomy, authority, concurrency, and recovery. Consult at architectural decisions; ordinary implementation within an accepted design does not reopen it.
- xy-toolchain — the CLI, build/lint/test commands, and the tooling these principles run on. Install:
xy.npx skills add ariestools/ariestools-skills --skill xy-toolchain - ariestools-sdk — which utilities to use and how to import them. Read it when the repo depends on sdk-js packages;
@ariestools/*requires it only there, so it is often absent elsewhere. Install:xy skills lint.npx skills add ariestools/ariestools-skills --skill ariestools-sdk - ariestools-sdk-react — which package owns a component or hook, its peers, and the import rule that keeps one copy of each React context. Read it when the repo depends on sdk-react packages; since toolchain 10.1.4,
@ariestools/sdk-react*requires it only there. Install:xy skills lint.npx skills add ariestools/ariestools-skills --skill ariestools-sdk-react - ariestools-actor — actor-kit actors, providers and the actor engine, hosted by cli-kit or browser-kit. Read it when the repo depends on actor-kit, cli-kit or browser-kit packages; since toolchain 10.1.4, requires it only there. Install:
xy skills lint.npx skills add ariestools/ariestools-skills --skill ariestools-actor - xy-agent — recommended, not required. Repository documentation conventions: the entry point, per-tool adapters, and the
AGENTS.mdanddocs/lifecycle. Read it when writing or reorganizing a repository's agent-facing documents, or when a repository already follows the pattern; otherwise follow the convention the repository already has. Inpapers/repos,@ariestools/toolchain(since toolchain 10.1.1) enforces it. Since 10.1.2,xy agent lintruns it only where the repository has a rootpnpm xy checkor declaresAGENTS.md(even only to set rule levels), and by default only a missing rootcommands.agentLintor a relative Markdown link in it whose target does not exist is an error. Other departures, such as aAGENTS.mdthat does not start with anCLAUDE.mdimport or a missing required@AGENTS.mdsection, warn, and fail only underAGENTS.mdor--strict. Toolchain 10.1.1 runs it in every repository with more error-level rules (version notes). See xy-toolchain ›XY_STRICT=1for the rules andxy agent.commands.agentLint.rulesscaffolds the convention without overwriting existing files. Install:pnpm xy agent init, or, since toolchain 10.1.2,npx skills add ariestools/ariestools-skills --skill xy-agent, which also records it as required sopnpm xy skills pick --skill xy-agentversion-checks it andpnpm xy skills lintinstalls or updates it. Since 10.1.2,--fixalso installs it in a new repository on any skills tier exceptxy repo init --skills-optional, although that flag's help still describes only XL1 skills. See xy-toolchain ›nonefor the other routes and their caveats.xy skills
这些是导航链接,而不是此 skill 的依赖;每个 skill 都需单独安装。
- ariestools-architecture — 关于自主性、权责、并发与恢复的共享设计偏好和审查标准。在进行架构决策时查阅;在既定设计内进行日常实现不会重新触发架构审查。
- xy-toolchain — CLI、build/lint/test 命令,以及这些原则所依托的工具。安装:
xy。npx skills add ariestools/ariestools-skills --skill xy-toolchain - ariestools-sdk — 应使用哪些 工具以及如何 import。仓库依赖 sdk-js 包时阅读;只有这些仓库才要求
@ariestools/*,因此在其他仓库中通常不会出现。安装:xy skills lint。npx skills add ariestools/ariestools-skills --skill ariestools-sdk - ariestools-sdk-react — 由哪个 包负责组件或 hook、其 peer dependency,以及确保每种 React context 仅保留一个副本的 import 规则。仓库依赖 sdk-react 包时阅读;自 toolchain 10.1.4 起,只有这些仓库才要求
@ariestools/sdk-react*。安装:xy skills lint。npx skills add ariestools/ariestools-skills --skill ariestools-sdk-react - ariestools-actor — 由 cli-kit 或 browser-kit 承载的 actor-kit actor、provider 和 actor engine。仓库依赖 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/的生命周期。编写或重组面向 Agent 的仓库文档时阅读;如果仓库已遵循该模式,也应阅读;否则遵循仓库已有的约定。在papers/仓库中,自 toolchain 10.1.1 起,@ariestools/toolchain会强制执行这些规范。自 10.1.2 起,只有当仓库存在根级xy agent lint或声明了AGENTS.md(即使只是为了设置规则级别)时,commands.agentLint才会运行该检查;默认情况下,仅将缺少根级pnpm xy check,或该文件中的相对 Markdown 链接目标不存在视为错误。其他偏差,例如AGENTS.md未以CLAUDE.mdimport 开头,或缺少必需的@AGENTS.md章节,会发出警告,且仅在AGENTS.md或--strict下失败。Toolchain 10.1.1 会在每个仓库中运行该检查,并应用更多 error 级别规则(版本说明)。有关规则和XY_STRICT=1,请参阅 xy-toolchain ›commands.agentLint.rules。xy agent会创建该规范的脚手架,但不会覆盖现有文件。安装:pnpm xy agent init;或者自 10.1.2 起使用npx skills add ariestools/ariestools-skills --skill xy-agent,后者还会将其记录为必需项,以便pnpm xy skills pick --skill xy-agent对其执行版本检查,并通过pnpm xy skills lint安装或更新。自 10.1.2 起,--fix在除xy repo init --skills-optional外的所有 skills 层级上,也会在新仓库中安装它,尽管该 flag 的帮助信息仍只描述 XL1 skills。有关其他安装方式和注意事项,请参阅 xy-toolchain ›none。xy skills