Icode

版本: v2.22.0

ICode 全流程编码工作流（步骤 0 + 1~6）

端到端编码工作流，将需求到交付拆解为严格步骤，每步可单独调用，方便你自行切换模型。本文档是路由器：内核规则内联，详细规则一律放 steps/*.md 与 references/*.md，需要时按路由表 Read（懒加载，省 token）。

• 步骤 0（可选）：需求初稿对话，多轮迭代后落档为 00_init.md（含链路图：修改前/后链路 + 改动点），独立步骤、不自动串联到步骤1
• 步骤 1~6：拟定计划 → 审查 → 定稿 → 编码 → 复检 → 终审

主流程步骤真源（防误用，唯一真源 = steps/ 目录，启动强制 Read）：步骤编号 / 产物文件名 / completed_steps 合法值一律以 steps/*.md 实时清单为准（ls steps/*.md 完整列出，含主流程与辅助入口 log / doc / limit / status / install / list / bak / verify / learn，及精简全流程入口 fast）——本块仅示意，steps/ 演进后以目录为准，勿依赖写死。/icode start / /icode fast / /icode plan 进入第一步先 ls steps/*.md 核对，不按"编码→测试→部署"直觉推断

• 当前主流程示意（以 ls steps/*.md 为准）：00_init → 01_plan → 02_review → 03_merge → 04_code → 05_deepcheck → 06_audit → 07_readme → 08_patch；不存在 03_code / 04_test / 05_deploy（测试验证在 04_code 子段，部署/回归归 07_readme / 08_patch / verify）
• 辅助独立步骤（doc / log / limit / status / install / list / bak / verify / learn）不参与 16 推进；fast 为精简全流程（非辅助独立步骤）——参与 16 但各步缩略（见命令表 fast 行）
• 强制：产物命名 + completed_steps 写号对照 ls steps/*.md 实时结果（如入口含 log → 可写 "log"），不在清单 → 停下核对，禁止自造产物占位；steps/ 目录与本文档不一致时以 steps/ 目录为准

通用约定（对话语言）

AI 对用户的回复一律使用中文（提示 / 解释 / 报告 / 追问 / 总结 / 决策说明 / 输出行）。工程内容保持原样、不翻译：代码、标识符、产物文件名、命令、日志原文、报错原文、设备输出、配置字段值。仅当用户明确要求英文回复时切换。

适用所有 /icode 命令的会话交互与步骤内对用户的询问/报告；产物文件正文遵循既有中文风格撰写。

调用命令

所有输出保存在 .icode_output/.icode_output_N/（N 自动递增）目录下。详细语义一律以 steps/*.md 为准，下表只给路由与关键 flag：

目录复用规则（start/plan/fast 启动时）：检查最新 .icode_output/.icode_output_N/——入口态（init_in_progress/log_done）有歧义一律问用户（带参可能是补充旧需求也可能是新需求）；非入口态带参 → 直接新建；无参且无入口态可复用 → 报错提示。完整脚本与 REUSE=2/0 语义见 references/dir_and_metadata.md「复用 / 创建新目录决策」。

init/log 入口状态转换时机：新工单先生成非空 ID 并经 create 原子出生；init 为 init_in_progress+["0"]，log 为 log_in_progress+[]，收尾经 transition 到 log_done 并追加 "log"；plan 产物/合同完成后经 transition 到 plan_done 并追加 "1"。禁止直写完成态。

公共选项（所有新建工单入口 init/log/start/plan/fast）：--worktree 用 git worktree 隔离（独立分支+目录，opt-in）；--debug（仅 init/log）独立孪生对照（目录建 .icode_output/.debug/、不入全局索引）。

控制面（工单 schema v3，vNext）

新工单一律 schema v3，经 tools/icode_control.py create 原子创建 metadata+出生事件；状态、metadata、事件、步骤端口/边界回检/回执、验证、索引与关闭均由控制面执行，禁止绕过直写。文中凡称“写/更新/追加 metadata”，除专用控制字段外，均指 metadata-update。机器真源：mcp/workflow-gate/gates.json + schemas/；执行器含 step/artifact/operation/policy/trace 等子命令。完整契约见 references/control_plane.md 与 references/execution_model.md。legacy 工单只读，变更前须迁移。

嵌入式、摄像头、邮件、技术文档、原理图与 MCU 项目不增加公开命令：既有 init/log/plan/code/doc/deepcheck/audit/verify 按 共享技能路由加载领域能力；显式网页邮件链接默认复用已登录浏览器并严格限定目标邮件阅读窗，原文/附件受控下载后由 tools/email_intake.py 离线解析 .eml/.msg，无人值守或邮箱范围搜索才使用可选的只读 IMAP 观察器；tools/embedded_profile.py 只读生成量化验证合同，tools/document_intake.py 只读检查异构文档/归档的真实类型、结构、hash、风险和覆盖，tools/media_router.py 根据宿主证明选择 native/bridge/dual/text_only 并生成视觉证据来源。邮箱观察保持无发送/回复/移动/删除/标记副作用，受保护资料不会被绕过，邮件/SDK/工具不会因摄取而执行，任何硬件写入、故障注入或测量仍需显式授权。

使用流程示例

完整示例见 README.md「快速开始」与各步骤文件；此处只给最小骨架。

/icode init 粗略需求 → /icode start 需求        # 全流程（步骤0 可选 + 1~6 串联）
/icode plan → review → merge → code → deepcheck → audit   # 分步手动
/icode readme / patch / verify --listen          # 交付报告 / 追加修改 / 纯实机验证
/icode status --pending                          # 跨工单验证债务
/icode learn --project .                          # 项目内使用观测的只读学习报告

• 日志根因分析入口：/icode log 设备日志+症状 → 根因报告 + 00_init.md → /icode start 衔接
• 全流程精简：/icode fast 需求；工程知识库：/icode doc；约束红线：/icode limit
• 中断/跨会话恢复：按 completed_steps 中 1~6 范围内最大已完成步骤续跑（见「全流程串联规则」）；重新执行某步骤可覆盖该步骤输出

锚点保留：方式 D2 / D3 / H——/icode log 的 TB 缺陷单拉取（方式 D2：单 LIB-NUM 复用+增量对抗；方式 D3：批量"打开/未完成"分析）——锚点兼容写法「方式H」/「方式 H」等价；钉钉文档拉取（方式 H）详见 steps/log.md「TB 缺陷源拉取」+「批量 TB 分析」 / tools/dingtalk/README.md。

通用规则

产物命名 + status 词表速查表（硬性速查，防"发明命名/状态"）

产物文件名与 status 值一律以 steps/XX_*.md 各步骤规定为准，下表只是速查不是第二真源（完整 status 语义见下方「status 字段枚举」段）。写产物 / 写 metadata 前对照下表核对，命名或状态不在表内 = 不合规（见下方「产物命名硬性条款」）。

主流程产物文件名（{ICODE_OUT_DIR}/ 下，全部小写、不得自造近似名）：

status 词表（写回 metadata 前逐字对照，禁止自定义）：正常流 log_in_progress / log_done → init_in_progress → plan_done → review_in_progress / review_done → plan_finalized → code_in_progress / code_done → deepcheck_in_progress / deepcheck_done → completed（终态）；debug 隔离流 debug_in_progress → debug_done。

产物命名硬性条款：产物必须按 steps/XX_*.md 规定的文件名、目录、格式产出；metadata 的 status 必须在本词表内。自定义文件名 / 自定义格式 / 词表外状态值 = 不合规，内容质量高也不能豁免——内容好 ≠ 机制合规。发现命名/状态不在上表，停下对照对应 steps/XX_*.md 修正，不得沿用自造近似（如用 03_merge.md 替代 03_plan_final.md、自造 audit_done 状态）。

强制阻断边界矩阵

按检查项的严重级别定义统一的"是否阻断流程"语义，避免规则散落在各 step 文件里：

各步骤声明的 L1/L2 检查项：详见对应 step 文件头部的「本步骤 L1/L2 检查项声明」段（已声明 7 个：plan / review / merge / code / deepcheck / audit / patch）。

• steps/01_plan.md 头部 → L1（前置产物缺失）/ L2（§3 缺失 + §10 ❌ > 3）
• steps/02_review.md 头部 → L1（前置产物缺失）/ L2（触达 absolute_cap，警告+记 metadata+继续）
• steps/03_merge.md 头部 → L1（03_plan_final.md 不是完整计划副本——定稿机器硬校验不通过，禁止进入步骤4）
• steps/04_code.md 头部 → L1（前置产物缺失）/ L2（Code Review Fix 全失败）
• steps/05_deepcheck.md 头部 → L1（前置产物缺失）
• steps/06_audit.md 头部 → L1（前置产物缺失）
• steps/08_patch.md 头部 → L1（无最新工单目录 / 入口态）/ L2（复检发现新引入问题，警告+记 metadata+继续）

L3·重要 检查项（不强制阻断，警告后流程继续）也已在各 step 头部声明段标注。

新增/修改检查项时：明确标注其 L 级别，写在 step 文件头部声明段。不明确的不算 L1-L4（默认按现有流程行为）。

目录管理（锚点保留，内容已迁移）

目录创建/复用/迁移/worktree 隔离规则已收敛到 references/dir_and_metadata.md 与 references/worktree_isolation.md（真源）。标题保留为锚点（文档可能用「SKILL.md「目录管理」段」指回）。

锚点保留小节：目录管理 / 目录管理·worktree 决策与创建 / 创建新目录 / 复用 / 创建新目录决策 / 检测最新目录

元信息文件（锚点保留，内容已迁移）

.ico_metadata.json 完整字段定义 / 模板 / verdict 字段族 / delivery_verdict / scope_escalations 等全部收敛到 references/dir_and_metadata.md（真源）+ schemas/ticket-metadata.schema.json。字段族标题保留为锚点（文档可能用「SKILL.md「verdict 字段族」」「SKILL.md「可选字段」」指回）。

锚点保留小节：元信息文件 / 可选字段 / verdict 字段族 / workload_estimate 字段族 / status 字段枚举 / status 写回校验 / 全局索引 / 模板

status 写回校验（强制，防词表外值落盘）：每步写 .ico_metadata.json 前，必须先对照上方词表校验 status 在枚举内（completed_steps 中的步骤号须是 steps/*.md 清单里存在的合法值），词表外值直接判不合规、拒绝写回并修正。校验用一行命令：

python3 -c "import json,sys; d=json.load(open('{ICODE_OUT_DIR}/.ico_metadata.json')); valid={'init_in_progress','plan_done','review_in_progress','review_done','plan_finalized','code_in_progress','code_done','deepcheck_in_progress','deepcheck_done','completed','log_in_progress','log_done','debug_in_progress','debug_done'}; s=d.get('status'); print('status:', s); sys.exit(0 if s in valid else 1)"

执行模式

所有步骤（含可选步骤0）在主会话中执行，使用当前会话模型。不主动切换模型，用户如需切换可手动 /model。

强制思考前置 + 反偷懒约束（所有步骤必须遵守，硬性总则）

完整规则见下表两真源（步骤执行前必须 Read 完整内容，不得凭 SKILL.md 概述或记忆执行——见反偷懒第 15 条）：

根因优先决策准则（修复缺陷逻辑本身，优先于规避/绕过/补丁/开关）

多方案并存时，第一优先 = 修正缺陷逻辑本身（root cause）；规避 / 重试 / 打补丁 / 加配置开关 = 降级选项，仅在根因不可行（须给出可验证的不可行论证）时选用。「保持安全门控」与「修正错误逻辑」不是互斥——根因方案在红线内部保持安全属性，而非因红线直接排除根因选项。细则落点：steps/01_plan.md §4 ADR（选型排序 + 强制判定问题）、steps/log.md（根因多候选 → 诊断先行）、steps/08_patch.md（旁路修复后强制回主验收闭环）。

全流程串联规则

/icode start 执行步骤1后，如果会话断开，恢复时必须读取 .ico_metadata.json 的 completed_steps，从最后一个完成步骤的下一步继续。不可跳过未完成的步骤。

续跑判定规则：以 completed_steps 中编号 1~6 范围内最大的已完成步骤为基准推进下一步。"0" 和 "log" 仅作为"已走过步骤0/log入口"的标记，不影响推进逻辑。例：["0"]/["log"] → 下一步是步骤1；["0","1"]/["log","1"] → 下一步是步骤2。

转换点门禁（自动串联硬门禁，防"前一步产物缺失/状态异常仍自说自话推进"）：/icode start / /icode fast 串联推进到下一步前，必须机器校验上一步产物存在 + status 已到对应完成态，任一项不满足即停止串联，输出"前一步产物缺失/状态异常，停止串联；请先补跑上一步或对照 steps/XX_*.md 修正"：

校验命令示例（推进到步骤4 前）：

test -f "{ICODE_OUT_DIR}/03_plan_final.md" && python3 -c "import json,sys; d=json.load(open('{ICODE_OUT_DIR}/.ico_metadata.json')); sys.exit(0 if d.get('status')=='plan_finalized' else 1)" || echo "❌ 前一步产物缺失/状态异常，停止串联"

与「前置文件校验」表（本段下方）的关系：前置校验表是单步命令入口的 L1 检查，本门禁是 start/fast 自动串联时每步转换点的强制复查——两者共用同一产物判据，自动串联下不因"上一步刚跑完"而跳过复查（本轮实测教训：自动串联下 03_plan_final.md 缺失仍推进到步骤6）。

patch 不参与推进判定：/icode patch 是横向追加修改，不改 status/completed_steps，不影响续跑判定——completed 工单 patch 后仍是 completed，code_done 工单 patch 后仍是 code_done（补丁记录在 patch_count/patch_history 字段 + 08_patch.md 产物，详见 steps/08_patch.md）。

patch 与主流程步骤的配合：patch 插在不同步骤之间时，后续代码相关步骤的计划侧基准须纳入补丁（补丁的增量计划/实施是已落地的设计依据），否则会覆盖 patch 修改或误判为偏离：

统一规则：步骤 4/5/6（代码相关步骤）启动时 Read {ICODE_OUT_DIR}/08_patch.md（存在且有 Patch 段才需配合；不存在走原流程）。步骤 2/3 只动计划文档、不碰代码，无需读补丁。决策锚点 patch_summary 已随 patch 刷新，下游读锚点时可感知补丁存在（references/decision_anchors.md）。

步骤 2/5 的 *_in_progress 状态 + 轮次计数器支持断点续跑（步骤0的 init_in_progress 不参与，详见上节"两种语义"）；步骤 4 的 code_in_progress（编译失败时保留）支持整体续跑——重跑步骤4时在已写入的代码基础上继续修复（编译失败时代码文件和 code_files 已保留落盘，不丢弃、不从计划重新编码），不带轮次断点。

工作流硬门禁（workflow gate，P0 四类 + P1 生命周期验收）

机器可判定硬门禁。真源 = mcp/workflow-gate/gates.json（触发条件/阻断步骤/必填单元/状态机只从这里读），校验器 = python3 tools/lint_workflow_contract.py <out_dir> [--step <step>] [--strict] [--json]（0=通过/1=有阻断/2=参数错）。旧工单缺 workflow_gate_schema_version → legacy-untracked 提示（--strict 判失败）。历史出处 docs/adr/ADR-0001-optimization-proposal-provenance.md。

四类硬门禁 + 生命周期验收（机器判定，步骤转换前跑校验器）：

• 语义决策门禁：semantic_decisions 存在 status != resolved 且非 diagnosis_only → plan/code/patch 阻断；诊断可结束但须显式 diagnosis_only=true
• 身份变化影响合同：identity_change=true 且 completeness != complete → code/deploy/audit-verified 阻断；9 维必答必带证据
• 需求增量回流：requirement_deltas 分类 needs_user_confirm/needs_replan → 冻结点，未分流不得继续扩大设计/验收矩阵
• 快速模式自动升级：mode=fast 命中 fast_risk_triggers 且 effective_mode != full 且 override != true → 违规
• 生命周期验收：涉及生命周期/身份变化时 acceptance_contract.matrix 必须覆盖全部 phases × consumers 必填单元，只验证直接查询不能 delivery_verdict=verified

字段族定义与写入点见 references/dir_and_metadata.md（scope_contract / requirement_deltas / semantic_decisions / impact_contract / acceptance_contract / risk_profile / delivery_verdict）。

历史检索复用（锚点保留，内容已迁移）

两段式检索 + 命中续期 + 过时校验（5 步）+ verdict 分流注入 + _inject_cache.json/patterns.json/project_docs 契约全部收敛到 references/dir_and_metadata.md + references/thinking_detail.md。标题保留为锚点。

锚点保留小节：历史检索复用 / 历史检索复用·注入分流 / 注入形式·按 verdict 分流 / 检索注入流程 / 零命中不注入，不强凑参考

注意事项

• Git 安全：禁止执行任何 Git 危险操作（git reset --hard、git push --force 等），也禁止 git commit 和 git push。git worktree add / git worktree remove 允许执行（不在禁止列）：创建/清理须用户确认（写操作影响 .git），永不自动 --force remove（未提交改动时 remove 失败是保护，见「目录管理·worktree 决策与创建」）
• .icode_output/ 父目录及其下的 .icode_output_N/ 目录无需用户确认：该目录下创建/写入/修改 .md/.json/.log 文件均为安全操作
• 工程污染防护：.icode_output/ 是 icode 产物目录，建议在工程 .gitignore 中加入 .icode_output/，避免产物误提交；icode 本身不自动修改工程的 .gitignore（工程配置由用户掌控）。历史检索的全局索引位于 ~/.claude/icode_data/，不在任何工程内，无污染风险；/icode doc 的工程文档库位于 ~/.claude/icode_data/project_docs/，同样不在任何工程内、不写工程内任何文件（用户工程内已有 doc/workflows/ 等历史文档时，忽略不读取不迁移不删除，从零生成到全局）

.icode_output/ 父目录语义（本次新增，含 limit.local 子目录）： .icode_output/ 父目录下含两类内容——

1. .icode_output/.icode_output_N/ 子目录 = 工单产物（每工单一目录，跟随工单生命周期，详见各步骤执行步骤）
2. .icode_output/limit.local/ 子目录 = 项目约束红线的单 checkout 覆盖（/icode limit 步骤产物，团队私有约定，自动 gitignore。limit 主存始终在全局 ~/.claude/icode_data/limits/<project_id>.md，跨 checkout 共享；local 完全覆盖 main。详见 steps/limit.md）

.icode_output/ 父目录默认 gitignore 不上传——这同时承担"产物容器 + 项目配置"两种角色，与上方「工程污染防护」建议的 gitignore 策略一致，无需特殊白名单配置

• 跨会话恢复：运行 ls -d .icode_output/.icode_output_* 确认目录后，直接调用对应步骤即可
• 中断恢复：重新执行某步骤可覆盖该步骤输出

MCP 调用覆盖强制化（锚点保留，内容已迁移）

MCP 分级语义（🟢/🟢*/⚪）、双保险机制、每步骤推荐表、分级思考 L0-L3、cheap-research 覆盖门 全部收敛到 references/mcp_per_step.md + references/mcp_integration.md + references/thinking_core.md（真源）。7 个 ICODE 本地 MCP 的 step→server/tool/operation 机器真源为 mcp/icode-mcp-policy/policy.json，不新增公开 /icode 命令。标题保留为锚点。

锚点保留小节：MCP 调用覆盖强制化 / MCP 工具集 / cheap-research 15 工具会话内缓存 / 降级标签格式规范 / 工具调用模式规范

关于外部工具调研：对于"是否值得引入第三方代码工具以优化 iCode"的判断结论（如 Tree-sitter 图谱、blast-radius 思路等），非 SKILL 集成、零必装依赖——iCode 主流程不依赖、不推荐、不安装任何外部工具。

各步骤详细规则

各步骤的详细 prompt、维度要求、执行流程请读取对应文件：

执行步骤时，必须先读取对应的 steps/XX_*.md 文件，按其中的详细指令执行。

决策锚点机制（步骤间思考传递）

解决「步骤间只传产物文件，AI 思考推理不传」痛点。各步骤完成后写 .decision_anchors.json（关键决策摘要），下游启动时读，不用重读产物全文。锚点是精炼摘要非产物备份。

• 文件：{ICODE_OUT_DIR}/.decision_anchors.json（工单目录内，与 .ico_metadata.json 平级）
• 写时机：init/plan/code/deepcheck/audit 完成后（L3 自动，AI 主动提炼）；patch 完成后追加 patch_summary + 刷新 open_risks（增量刷新，不覆盖主流程字段）
• 读时机：plan/review/code/deepcheck/audit/patch 启动时（L4 自动）
• 开关：metadata.anchors_enabled（默认 true，false 跳过，向后兼容旧工单）
• 完整规则：references/decision_anchors.md

共享规则文件（references/）

各 step 文件不再重复定义跨步骤共享的规则，统一引用 references/ 下的共享文件。执行某步骤时若该步骤引用了共享文件，必须先用 Read 工具实读该文件完整内容（不得凭 SKILL.md 概述或记忆执行，否则产出不合规——见反偷懒第15条）：