Back to Details

implementation-strategy

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Implementation Strategy

实现策略

Overview

概述

Use this skill before editing code when the task changes runtime behavior or anything that might look like a compatibility concern. The goal is to keep implementations simple while protecting real released contracts and genuinely supported external state.
在修改运行时行为或任何可能涉及兼容性问题的内容时，请在编辑代码前使用本技能。我们的目标是保持实现简洁，同时切实保护已发布的契约和官方支持的外部状态。

Quick start

快速开始

  1. Identify the surface you are changing: released public API, unreleased branch-local API, internal helper, persisted schema, wire protocol, CLI/config/env surface, or docs/examples only.
  2. Determine the latest release boundary from 
    origin
    first, and only fall back to local tags when remote tags are unavailable:
    bash
    LATEST_RELEASE_TAG="$(
  git ls-remote --tags --refs origin 'v*' 2>/dev/null |
    awk -F/ '{print $3}' |
    sort -V -r |
    head -n1
)"
if [ -z "$LATEST_RELEASE_TAG" ]; then
  LATEST_RELEASE_TAG="$(git tag -l 'v*' --sort=-v:refname | head -n1)"
fi
printf '%s\n' "$LATEST_RELEASE_TAG"
  3. Judge breaking-change risk against that latest release tag, not against unreleased branch churn or post-tag changes already on 
    main
    . If the command fell back to local tags, treat the result as potentially stale and say so.
  4. Prefer the simplest implementation that satisfies the current task. Update callers, tests, docs, and examples directly instead of preserving superseded unreleased interfaces.
  5. Add a compatibility layer only when there is a concrete released consumer, an otherwise supported durable external state that requires it, or when the user explicitly asks for a migration path.
  1. 确定你要修改的作用域：已发布的公共API、未发布的分支本地API、内部辅助函数、持久化schema、通信协议、CLI/配置/环境变量作用域，或者仅文档/示例内容。
  2. 首先从
    origin
    确定最新的版本边界，只有远程标签不可用时才回退到本地标签：
    bash
    LATEST_RELEASE_TAG="$(
  git ls-remote --tags --refs origin 'v*' 2>/dev/null |
    awk -F/ '{print $3}' |
    sort -V -r |
    head -n1
)"
if [ -z "$LATEST_RELEASE_TAG" ]; then
  LATEST_RELEASE_TAG="$(git tag -l 'v*' --sort=-v:refname | head -n1)"
fi
printf '%s\n' "$LATEST_RELEASE_TAG"
  3. 基于最新的发布标签判断破坏性变更风险，不要基于未发布的分支变更或
    main
    分支上标签发布后的提交内容判断。如果命令回退到了本地标签，请明确说明结果可能已过时。
  4. 优先选择能满足当前任务的最简单实现。直接更新调用方、测试、文档和示例，而不是保留已被取代的未发布接口。
  5. 仅当存在具体的已发布使用者、有其他需要支持的持久化外部状态，或用户明确要求提供迁移路径时，才添加兼容层。

Compatibility boundary rules

兼容性边界规则

  • Released public API or documented external behavior: preserve compatibility or provide an explicit migration path.
  • Persisted schema, serialized state, wire protocol, CLI flags, environment variables, and externally consumed config: treat as compatibility-sensitive once they are released or otherwise have a supported external consumer. Unreleased post-tag formats that only exist on the current branch can still be rewritten directly.
  • Interface changes introduced only on the current branch: not a compatibility target. Rewrite them directly.
  • Interface changes present on 
    main
    but added after the latest release tag: not a semver breaking change by themselves. Rewrite them directly unless they already back a released or otherwise supported durable format.
  • Internal helpers, private types, same-branch tests, fixtures, and examples: update them directly instead of adding adapters.
  • 已发布的公共API或有文档记录的外部行为：保持兼容性，或提供明确的迁移路径。
  • 持久化schema、序列化状态、通信协议、CLI flags、环境变量和外部使用的配置：一旦发布或存在受支持的外部使用者，就视为对兼容性敏感。仅存在于当前分支、尚未发布的标签后格式仍然可以直接重写。
  • 仅在当前分支引入的接口变更：不属于兼容性保护目标，可以直接重写。
  • 存在于
    main
    分支但在最新发布标签之后添加的接口变更：本身不构成semver破坏性变更。可以直接重写，除非它们已经支撑了已发布或其他受支持的持久化格式。
  • 内部辅助函数、私有类型、同分支测试、测试用例数据和示例：直接更新即可，无需添加适配器。

Default implementation stance

默认实现立场

  • Prefer deletion or replacement over aliases, overloads, shims, feature flags, and dual-write logic when the old shape is unreleased.
  • Do not preserve a confusing abstraction just because it exists in the current branch diff.
  • If review feedback claims a change is breaking, verify it against the latest release tag and actual external impact before accepting the feedback.
  • If a change truly crosses the latest released contract boundary, call that out explicitly in the ExecPlan, changeset, and user-facing summary.
  • 当旧形态尚未发布时，优先选择删除或替换，而非使用别名、重载、shims、功能开关和双写逻辑。
  • 不要仅仅因为某个令人困惑的抽象存在于当前分支diff中就保留它。
  • 如果评审反馈认为某个变更是破坏性的，请先对照最新发布标签和实际外部影响验证，再接受反馈。
  • 如果变更确实跨越了最新发布的契约边界，请在ExecPlan、变更集和面向用户的摘要中明确指出。

When to stop and confirm

何时需要停止并确认

  • The change would alter behavior shipped in the latest release tag.
  • The change would modify durable external data or protocol formats that are already released or otherwise supported.
  • The user explicitly asked for backward compatibility, deprecation, or migration support.
  • 变更会修改最新发布标签中已上线的行为。
  • 变更会修改已发布或其他受支持的持久化外部数据或协议格式。
  • 用户明确要求向后兼容、弃用提示或迁移支持。

Output expectations

输出预期

When this skill materially affects the implementation approach, state the decision briefly in your reasoning or handoff, for example:
  • Compatibility boundary: latest release tag v0.x.y; branch-local interface rewrite, no shim needed.
  • Compatibility boundary: latest release tag v0.x.y; unreleased RunState snapshot rewrite, no shim needed.
  • Compatibility boundary: released RunState schema; preserve compatibility and add migration coverage.
当本技能对实现方案有实质性影响时，请在你的推理或交接内容中简要说明决策，例如：
  • Compatibility boundary: latest release tag v0.x.y; branch-local interface rewrite, no shim needed.
  • Compatibility boundary: latest release tag v0.x.y; unreleased RunState snapshot rewrite, no shim needed.
  • Compatibility boundary: released RunState schema; preserve compatibility and add migration coverage.