coding-preflight git:20260908.7e2cb50A

Immutable. This exact content is served forever at /api/v1/blob/7c953063ad3b62c6.

---
name: coding-preflight
description: >-
  在 echo-agent 开始缺陷修复、功能开发、重构、契约或样式改动前，先完成复用搜索、架构分层、状态权威、
  修改边界和验证范围预检；当新需求可能导致重复代码、相近概念、公共接口漂移或风格分裂时使用，不负责首次全量语义建库。
metadata:
  category: 工程质量
  scope: 框架
---

# 编码前预检

目标是让 AI 在写代码前先证明“为什么要改这里、为什么不能复用已有能力、改动后由谁继续拥有语义”。
这是开发指导，不是新的权限门控或运行时状态机。

## 预检顺序

1. 记录当前分支、提交标识、未提交状态、生效的 `AGENTS.md` 和用户授权范围；现有改动归原所有者。
2. 暂定一个 `primary_kind`：缺陷修复（`bugfix`）、功能开发（`feature`）、重构（`refactor`）、契约（`contract`）
   或样式（`style`），并独立标记公共接口、持久化、生命周期、并发/恢复、外部副作用、跨 crate、未知证据等风险。
   首个差异产生后重新分类，只能升级。
3. 按类型名、trait、字段、行为、相邻命名和调用路径搜索整个 `echo-agent` 工作空间；区分定义、注册、可达和已验证。
4. 明确通用框架机制、使用方策略和适配边界。公共接口即使当前无内部调用，也不能仅凭
   “EKO 没使用”删除。
5. 检查是否引入新的状态权威、任务图、存储接口、协议、状态机、并发许可或近义术语；可以扩展现有权威时禁止平行实现。
6. 读取相邻实现确定命名、错误处理、UTF-8、禁止崩溃、模块边界、测试和文档风格；不要为了一致性做无关全仓格式化。

## 输出合同

在写代码前给出：变更分类与风险、已有可复用能力、分层结论、唯一权威、允许修改范围、明确不触碰范围、
需要删除或迁移的旧路径、文档/示例/SDK Skill 影响，以及验证矩阵。

出现新的架构、状态权威、公共协议或真实产品取舍时先进入设计/人工裁决；事实已清楚的局部改动直接实施。
预检结论是任务内工作合同，不落盘为第二份长期语义权威。

## 阶段衔接

1. 普通局部改动在预检通过后进入编码。
2. 架构重构、新状态权威、公共协议或重复实现收敛先读取
   [架构收敛工作流](workflows/architecture-convergence.md)，完成方案与迁移门禁后再编码。
3. 首个实际代码差异形成后，已有 `semantic/` 基线时调用 `semantic-diff`，重新确认风险和最终验证矩阵；
   尚未建基线时只完成任务内局部语义影响检查并明确该缺口，不伪造对象，也不阻塞普通局部改动。用户目标包含
   建立基线时再调用 `semantic-discover`。风险深度只能升级。
4. 执行测试、静态检查、类型、契约和集成验证。任何失败都先定位根因，不能跳过。
5. 只有 `semantic-diff` 产生高风险失效单元、残余风险、新问题或事故关联时，才调用 `semantic-audit`。
6. 语义材料被创建、更新或问题记录需要关闭时调用 `semantic-verify`，然后才能进入完成声明和仓库提交门禁。

维护这些 Skill 的触发描述时，读取 [路由走查样例](references/routing-cases.md) 并逐项确认应触发与不应触发项。