xy-development

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Development Standards

开发标准

Authority. This skill is maintained only in
ariestools/ariestools-skills
. Copies under
XYOracleNetwork/xyo-skills
are redirect stubs — edit here, never there.
Skill identity. When you present a plan, an acknowledgement, or a completion summary, state which skills informed it as
xy-development v<version>
, and list each other active skill from this pack the same way. Read the version from this file's
metadata.version
, never from an example.
This skill defines foundational development practices. Where a repository's own
AGENTS.md
or
CLAUDE.md
says otherwise, the repository wins. Load the sub-topic that matches your current task:
Architecture 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-skills
中维护。
XYOracleNetwork/xyo-skills
下的副本均为重定向占位文件——请在此处编辑,切勿在那些副本中编辑。
Skill 身份。 当你提交计划、确认说明或完成总结时,应说明哪些 skill 为其提供了依据,格式为
xy-development v<version>
,并以相同方式列出本 skill 包中的每个其他活动 skill。始终从此文件的
metadata.version
读取版本,绝不要从示例中读取。
此 skill 定义了基础开发实践。如果仓库自身的
AGENTS.md
或
CLAUDE.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
any
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.
编写、审查或重构 TypeScript 代码,或整理 import 时阅读。涵盖严格性标记和代码形态限制;
any
策略;返回类型;interface 与 type 的区别;readonly 用法;可擦除语法规则(禁止 enum、参数属性或 namespace);仅支持 ESM 的模块与显式 import 扩展名;根 barrel import 与 import 风格;条件、nullish 值和 Promise;以及命名、导出和文件约定。

Git 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
AGENTS.md
or
origin/develop
, merge methods, and releases.
提交、分支、推送、合并或创建 PR,撤销变更,处理被拒绝的推送,或发布版本时阅读。涵盖 conventional commit 和 PR 标题、原子提交、提交身份与仓库整洁性、历史重写策略(共享分支保持仅追加;未推送的主题分支仅在用户要求时改写)、在分配给你的 checkout 中工作、根据
AGENTS.md
或
origin/develop
检测分支模型、合并方式以及发布流程。

Deployment Conventions

部署规范

Read when creating, changing, simplifying, or migrating deployment workflows or provider branch mappings. Covers
<environment>[-<component>]-<target>[-<build-mode>]
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.
创建、修改、简化或迁移部署工作流或 provider 分支映射时阅读。涵盖
<environment>[-<component>]-<target>[-<build-mode>]
命名规则、原生 Vercel 与 CI 预构建/镜像交付、仅保留一条自动构建/部署路径、命名例外需明确批准、homelab 适用范围,以及独立部署组件之间的兼容性。

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
xy build
and
xy test
, with
xy check
only for policy and document edits, plus browser verification for apps), and writing project-specific acceptance criteria.
运行任何 build、lint、test 或 dev 命令之前,添加或升级依赖之前,编写 PRD.md 的验收标准之前,以及宣布任何任务完成之前阅读。涵盖工具链发现(先从仓库说明、scripts 和 CI 中发现工具链,而不是临时执行零散命令)、依赖和 peer dependency 规则、凭据安全、分层的完成定义(toolchain 完成门禁限定为
xy build
和
xy test
,
xy check
仅用于策略和文档编辑,应用还需进行浏览器验证),以及编写项目特定的验收标准。

Behavior-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
    xy
    CLI, build/lint/test commands, and the tooling these principles run on. Install:
    npx skills add ariestools/ariestools-skills --skill xy-toolchain
    .
  • ariestools-sdk — which
    @ariestools/*
    utilities to use and how to import them. Read it when the repo depends on sdk-js packages;
    xy skills lint
    requires it only there, so it is often absent elsewhere. Install:
    npx skills add ariestools/ariestools-skills --skill ariestools-sdk
    .
  • ariestools-sdk-react — which
    @ariestools/sdk-react*
    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,
    xy skills lint
    requires it only there. Install:
    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,
    xy skills lint
    requires it only there. Install:
    npx skills add ariestools/ariestools-skills --skill ariestools-actor
    .
  • xy-agent — recommended, not required. Repository documentation conventions: the
    AGENTS.md
    entry point, per-tool adapters, and the
    docs/
    and
    papers/
    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. In
    @ariestools/toolchain
    repos,
    xy agent lint
    (since toolchain 10.1.1) enforces it. Since 10.1.2,
    pnpm xy check
    runs it only where the repository has a root
    AGENTS.md
    or declares
    commands.agentLint
    (even only to set rule levels), and by default only a missing root
    AGENTS.md
    or a relative Markdown link in it whose target does not exist is an error. Other departures, such as a
    CLAUDE.md
    that does not start with an
    @AGENTS.md
    import or a missing required
    AGENTS.md
    section, warn, and fail only under
    --strict
    or
    XY_STRICT=1
    . Toolchain 10.1.1 runs it in every repository with more error-level rules (version notes). See xy-toolchain ›
    xy agent
    for the rules and
    commands.agentLint.rules
    .
    pnpm xy agent init
    scaffolds the convention without overwriting existing files. Install:
    npx skills add ariestools/ariestools-skills --skill xy-agent
    , or, since toolchain 10.1.2,
    pnpm xy skills pick --skill xy-agent
    , which also records it as required so
    pnpm xy skills lint
    version-checks it and
    --fix
    installs or updates it. Since 10.1.2,
    xy repo init --skills-optional
    also installs it in a new repository on any skills tier except
    none
    , although that flag's help still describes only XL1 skills. See xy-toolchain ›
    xy skills
    for the other routes and their caveats.
这些是导航链接,而不是此 skill 的依赖;每个 skill 都需单独安装。
  • ariestools-architecture — 关于自主性、权责、并发与恢复的共享设计偏好和审查标准。在进行架构决策时查阅;在既定设计内进行日常实现不会重新触发架构审查。
  • xy-toolchain —
    xy
    CLI、build/lint/test 命令,以及这些原则所依托的工具。安装:
    npx skills add ariestools/ariestools-skills --skill xy-toolchain
    。
  • ariestools-sdk — 应使用哪些
    @ariestools/*
    工具以及如何 import。仓库依赖 sdk-js 包时阅读;只有这些仓库才要求
    xy skills lint
    ,因此在其他仓库中通常不会出现。安装:
    npx skills add ariestools/ariestools-skills --skill ariestools-sdk
    。
  • ariestools-sdk-react — 由哪个
    @ariestools/sdk-react*
    包负责组件或 hook、其 peer dependency,以及确保每种 React context 仅保留一个副本的 import 规则。仓库依赖 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 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/
    和
    papers/
    的生命周期。编写或重组面向 Agent 的仓库文档时阅读;如果仓库已遵循该模式,也应阅读;否则遵循仓库已有的约定。在
    @ariestools/toolchain
    仓库中,自 toolchain 10.1.1 起,
    xy agent lint
    会强制执行这些规范。自 10.1.2 起,只有当仓库存在根级
    AGENTS.md
    或声明了
    commands.agentLint
    (即使只是为了设置规则级别)时,
    pnpm xy check
    才会运行该检查;默认情况下,仅将缺少根级
    AGENTS.md
    ,或该文件中的相对 Markdown 链接目标不存在视为错误。其他偏差,例如
    CLAUDE.md
    未以
    @AGENTS.md
    import 开头,或缺少必需的
    AGENTS.md
    章节,会发出警告,且仅在
    --strict
    或
    XY_STRICT=1
    下失败。Toolchain 10.1.1 会在每个仓库中运行该检查,并应用更多 error 级别规则(版本说明)。有关规则和
    commands.agentLint.rules
    ,请参阅 xy-toolchain ›
    xy agent
    。
    pnpm xy agent init
    会创建该规范的脚手架,但不会覆盖现有文件。安装:
    npx skills add ariestools/ariestools-skills --skill xy-agent
    ;或者自 10.1.2 起使用
    pnpm xy skills pick --skill xy-agent
    ,后者还会将其记录为必需项,以便
    pnpm xy skills lint
    对其执行版本检查,并通过
    --fix
    安装或更新。自 10.1.2 起,
    xy repo init --skills-optional
    在除
    none
    外的所有 skills 层级上,也会在新仓库中安装它,尽管该 flag 的帮助信息仍只描述 XL1 skills。有关其他安装方式和注意事项,请参阅 xy-toolchain ›
    xy skills
    。