Back to Details

stand-general

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Coding Standards

编码标准

Global standards that apply to all projects and languages.
适用于所有项目和语言的全局标准。

Single Source of Truth

单一事实来源

Any value defined in one place and consumed in another should be referenced, not copied. Applies to versions, paths, URLs, schema constants, and configuration.
  • If two files would need to be updated in lockstep, the second is a derived artifact — generate it, don't hand-maintain it.
  • CI verification of two files agreeing is a smell: the right pattern is run-the-generator + 
    git diff --exit-code
    , not parse-and-compare.
  • Hand-maintained mirrors of canonical sources rot silently. The cost of a small generator is always lower than the cost of recurring drift bugs.
任何在一处定义并在另一处使用的值都应通过引用获取，而非复制。适用于版本、路径、URL、模式常量和配置。
  • 如果两个文件需要同步更新，那么第二个文件是派生产物——应生成它，而非手动维护。
  • CI验证两个文件内容一致是不良实践：正确的模式是运行生成器 + 
    git diff --exit-code
    ，而非解析后对比。
  • 手动维护的规范源镜像会悄然失效。编写一个小型生成器的成本永远低于反复处理漂移bug的成本。

Before You Write

编写前准备

Before implementing utility logic (file traversal, string parsing, config lookup, error wrapping), search the codebase for an existing implementation.
  • Found a close match? Import or extend it instead of reimplementing.
  • Same pattern already in 2+ files? Extract it to a shared module before adding a third instance.
  • Duplication accumulates one compliant PR at a time — prevent it at writing time rather than relying on later audits.
在实现工具类逻辑（文件遍历、字符串解析、配置查找、错误包装）之前，先在代码库中搜索现有实现。
  • 找到相近实现？直接导入或扩展它，而非重新实现。
  • 相同模式已出现在2个及以上文件中？在添加第三个实例前，将其提取到共享模块。
  • 代码重复会随着一个个合规的PR逐渐累积——要在编写时就预防，而非依赖后续审计。

Pre-Implementation

预实现检查

Answer three questions before creating a new file, module, or significant function:
  1. Does this logic already exist? Search first; reuse beats rewrite.
  2. Is this the right module? An existing module growing too large is a signal to refactor it, not to create a parallel module beside it.
  3. Will this create duplication later? If similar future cases are foreseeable, put the logic in a shared location from the start.
在创建新文件、模块或重要函数前，先回答三个问题：
  1. 该逻辑是否已存在？ 先搜索；复用优于重写。
  2. 这是合适的模块吗？ 现有模块过于庞大是重构的信号，而非在其旁创建并行模块。
  3. 这会在未来造成重复吗？ 如果可预见类似的未来场景，从一开始就将逻辑放在共享位置。

Architectural Awareness

架构意识

When adding a module or significant function:
  • Confirm it fits the layer it lives in, and that its dependency direction matches the existing architecture.
  • Every new dependency arrow between modules must be intentional — never a side effect of convenient imports.
  • A module growing past ~300–400 lines is a signal to split it along responsibility boundaries.
添加模块或重要函数时：
  • 确认它符合所在层级，且依赖方向与现有架构一致。
  • 模块间新增的每个依赖箭头都必须是有意为之——绝不能是便捷导入带来的副作用。
  • 模块代码超过约300-400行时，应按职责边界拆分。

Dependency Update Triage (Renovate/Dependabot)

依赖更新处理（Renovate/Dependabot）

  • Merge safe green bumps. For breaking major bumps, fix and migrate — never just close the PR to dodge the work.
    • Don't: close a failing Astro 6→7 Renovate PR because 
      @astrojs/tailwind
      no longer builds.
    • Do: migrate to the replacement (
      @tailwindcss/vite
      ) in the same PR, then merge.
  • Green doesn't mean safe. On a repo where CI doesn't cover every path, a green PR can still be broken in the un-CI'd parts. Validate those parts locally before merging, not just the parts CI checks.
  • Backlog handling for dependency issues/PRs (closing, repurposing, announcing changes): follow the 
    issue
    skill's Backlog Stewardship section.
  • 合并安全的绿色版本更新。 对于破坏性的大版本更新，要修复并迁移——绝不能仅关闭PR来逃避工作。
    • 错误做法：因
      @astrojs/tailwind
      无法构建而关闭Astro 6→7的Renovate失败PR。
    • 正确做法：在同一个PR中迁移至替代方案（
      @tailwindcss/vite
      ），然后合并。
  • 绿色不代表安全。 在CI未覆盖所有路径的仓库中，绿色PR仍可能在未被CI检查的部分存在问题。合并前要在本地验证这些部分，而非仅依赖CI检查的内容。
  • 依赖问题/PR的积压处理（关闭、重新调整用途、公告变更）：遵循
    issue
    技能中的积压管理章节。

Per-repo agent context (
AGENTS.md
/ 
CLAUDE.md
)

仓库专属Agent上下文（
AGENTS.md
/ 
CLAUDE.md
）

Every target repo may carry a standing context file that assessment and implementation skills load automatically. Precedence: if both 
AGENTS.md
and 
CLAUDE.md
exist, 
AGENTS.md
is authoritative — apply it and do not also apply conflicting 
CLAUDE.md
instructions. If only one exists, use that file. If both exist and their requirements conflict in a way that blocks safe progress, stop and ask the user which wins rather than guessing. When present, treat its standards, constraints, and contract as binding for the session — do not re-type them from chat memory.
每个目标仓库可能包含一个常驻上下文文件，评估和实现类技能会自动加载该文件。优先级： 如果
AGENTS.md
和
CLAUDE.md
同时存在，
AGENTS.md
具有权威性——遵循它，且不应用
CLAUDE.md
中与之冲突的指令。如果仅存在其中一个，则使用该文件。如果两者都存在且要求冲突到阻碍安全推进的程度，请停止并询问用户以确定优先级，而非自行猜测。当文件存在时，其标准、约束和协议对当前会话具有约束力——请勿从聊天记忆中重新输入这些内容。

Expected sections

预期章节

Write the file so the per-repo delta is only the repo facts. Put recurring org-wide rules in an org preset section (or point at a shared org doc) rather than copying them into every repo.
  1. House standards pointers — toolchains (e.g. 
    uv
    / 
    bun
    / 
    lintro
    ), lint entry point, CI source / reusable workflows, model repos to copy conventions from, and any org-managed ruleset notes.
  2. Contract / operating agreement — autonomy level, merge policy (who merges, squash vs queue, signed commits), babysit/review expectations, and how the agent should surface vs keep going.
  3. Standing constraints — safety limits (e.g. no paid LLM API calls during assessment), scope rules, storage limits (e.g. local SQLite only), and no-side-effects rules for assessment-only work.
  4. Org preset — recurring org-wide rules referenced once so each repo file stays short; only repo-specific product/org facts belong outside this section.
编写该文件时，仓库专属差异应仅包含仓库特定事实。将重复出现的组织级规则放在组织预设章节（或指向共享组织文档），而非复制到每个仓库的文件中。
  1. 内部标准指引——工具链（如
    uv
    / 
    bun
    / 
    lintro
    ）、代码检查入口、CI源/可复用工作流、可复制约定的模型仓库，以及任何组织管理的规则集说明。
  2. 协议/操作约定——自主权限级别、合并策略（谁来合并、压缩合并还是队列合并、签名提交）、监控/评审预期，以及Agent应如何反馈问题或继续推进工作。
  3. 常驻约束——安全限制（如评估期间不调用付费LLM API）、范围规则、存储限制（如仅使用本地SQLite），以及仅评估工作的无副作用规则。
  4. 组织预设——重复出现的组织级规则仅引用一次，使每个仓库的文件保持简洁；只有仓库特定的产品/组织事实才需放在该章节之外。

Consumers

适用技能

At start of a run, these skills read the target repo's 
AGENTS.md
/ 
CLAUDE.md
when present and apply it as binding context:
  • analyze-project
  • implement-issues
  • babysit-pr
Missing the file is fine — fall back to chat instructions and 
stand-*
skills. Do not invent standing constraints that are not in the file or the user's message.
在运行开始时，以下技能会读取目标仓库的
AGENTS.md
/ 
CLAUDE.md
（如果存在）并将其作为绑定上下文应用：
  • analyze-project
  • implement-issues
  • babysit-pr
没有该文件也无妨——回退到聊天指令和
stand-*
类技能。请勿编造文件或用户消息中未提及的常驻约束。

Cross-cutting References

跨领域参考

  • Linting and formatting: follow the 
    lint
    skill
  • Ignoring lint issues: follow the 
    lint
    skill (Rules section)
  • Testing: follow the 
    test
    skill
  • Commits: follow the 
    commit
    skill
  • Pull requests: follow the 
    pr
    skill
  • Pre-push AI review (CodeRabbit): follow the 
    coderabbit
    skill
  • Pre-push AI review (Greptile): follow the 
    greptile
    skill
  • Per-repo standing context: see Per-repo agent context above
  • 代码检查与格式化：遵循
    lint
    技能
  • 忽略代码检查问题：遵循
    lint
    技能（规则章节）
  • 测试：遵循
    test
    技能
  • 提交：遵循
    commit
    技能
  • 拉取请求：遵循
    pr
    技能
  • 推送前AI评审（CodeRabbit）：遵循
    coderabbit
    技能
  • 推送前AI评审（Greptile）：遵循
    greptile
    技能
  • 仓库专属常驻上下文：参见上方仓库专属Agent上下文

Pre-push review workflow

推送前评审流程

CLI review mirrors CI and catches issues before slow CI completes. Default: run both Greptile and CodeRabbit when CI uses both.
Short flow:
text
commit → [greptile ‖ coderabbit] → pr
Explicit flow:
text
lint → test → commit → [greptile ‖ coderabbit] → pr
Each step names the skill to follow.
‖
means run greptile and coderabbit in parallel when possible. Fix findings, then optional verify pass. Do not re-run either CLI on unchanged code. CI remains the merge-time confirmation.
CLI评审与CI镜像一致，可在缓慢的CI完成前发现问题。默认规则：如果CI同时使用Greptile和CodeRabbit，则同时运行两者。
简化流程：
text
commit → [greptile ‖ coderabbit] → pr
完整流程：
text
lint → test → commit → [greptile ‖ coderabbit] → pr
每个步骤指明了要遵循的技能。
‖
表示尽可能并行运行greptile和coderabbit。修复发现的问题后，可选择验证是否通过。无需对未修改的代码重新运行任一CLI。CI仍是合并时的最终确认环节。