| name | implementation-strategy |
| description | 编辑代码前决定实现策略。用于任务会改变导出 API、运行时行为、序列化状态、测试或文档，并且需要判断兼容性边界、是否需要 shim/migration，以及未发布接口能否直接重写时。 |
实现策略
概览
当任务会改变运行时行为，或任何看起来可能涉及兼容性的内容时，在编辑代码前使用本 skill。目标是在保护真实已发布契约的同时，让实现保持简单。
快速开始
- 识别正在改变的 surface：已发布 public API、未发布 branch-local API、internal helper、persisted schema、wire protocol、CLI/config/env surface，或仅 docs/examples。
- 确定最新 release 边界：
BASE_TAG="$(git tag -l 'v*' --sort=-v:refname | head -n1)"
echo "$BASE_TAG"
- 按这个最新 release tag 判断 breaking-change risk，不要按未发布 branch churn 或
main 上 release 之后的变更判断。
- 优先选择满足当前任务的最简单实现。直接更新 callers、tests、docs 和 examples，不要保留已被取代的未发布接口。
- 只有存在具体 released consumer、受支持的 durable external state boundary 确实需要，或用户明确要求 migration path 时，才添加 compatibility layer。
兼容性边界规则
- Released public API 或 documented external behavior：保留兼容性，或提供明确 migration path。
- Persisted schema、serialized state、wire protocol、CLI flags、environment variables 和 externally consumed config：当它们属于最新 release，或仓库明确表示要跨 commit、process 或 machine 保留时，按 compatibility-sensitive 处理。
- 只在当前 branch 引入的 interface changes：不是 compatibility target，直接重写。
- 已在
main 但晚于最新 release tag 的 interface changes：本身不构成 semver breaking change。除非它们已经定义已发布或明确支持的 durable external state boundary，否则直接重写。
- Internal helpers、private types、same-branch tests、fixtures 和 examples：直接更新，不要添加 adapters。
main 上未发布的 persisted schema versions：当中间快照明确不受支持时，可在 release 前重新编号或 squash。
默认实现立场
- 当旧形态未发布时，优先删除或替换，而不是添加 aliases、overloads、shims、feature flags 或 dual-write logic。
- 不要因为某个混乱抽象已经存在于当前 branch diff，就保留它。
- 如果 review feedback 声称某个改动是 breaking change，先按最新 release tag 和真实外部影响核对，再接受反馈。
- 如果变更确实跨越最新 released contract boundary，在 implementation notes、release notes context 和用户可见总结中明确说明。
本项目兼容性规则
- Typer CLI surface（
harnesskit init、harnesskit integration ...、flags、arguments、exit behavior 和用户可见 messages）一旦发布，就按 compatibility-sensitive 处理。
- .harnesskit/config.json 是 durable external state。当前
schema_version 是 1；结构变化需要测试和明确兼容性决策。
- templates/ 下的 generated template output 是用户可见行为，因为
harnesskit init 会把它复制或渲染进目标仓库。
- 当前支持的 integration 是
codex；新增或重命名 integrations 会影响 CLI 行为、template layout、README guidance 和 tests。
- Jinja templates 使用
StrictUndefined；新增 template variables 必须提供对应 render context，或明确作为 target-repo TODO。
何时停止并确认
- 变更会改变最新 release tag 已发布的行为。
- 变更会修改 durable external data、protocol formats 或 serialized state。
- 变更会删除或重命名现有 CLI commands、flags、config keys、template output paths 或 supported integrations。
- 用户明确要求 backward compatibility、deprecation 或 migration support。
输出期望
当本 skill 实质影响实现方式时，在 reasoning 或 handoff 中简要说明决策，例如：
Compatibility boundary: latest release tag v0.x.y; branch-local interface rewrite, no shim needed.Compatibility boundary: released schema; preserve compatibility and add migration coverage.
