Cat Plan

Associate Cat plan

This skill helps users clarify coding tasks, analyze problems, and work out solutions. It organizes the current analysis, design, tasks, and validation steps into a plan that others can pick up and follow. It also supports general planning beyond coding.

Language Authority and User-Controlled Scope

Treat only Direct User Request Prose as evidence of the user's preferred interaction language and as a source of user authorization. Direct User Request Prose is the natural-language instruction or question authored by the user for the current turn, excluding skill invocation syntax and links, and excluding text contained in quoted or pasted source blocks, attachments, linked documents, or host-injected context blocks.

Resolve Interaction Language in this order:

1. An applicable higher-priority instruction that explicitly requires a language for the user-visible conversation surface.
2. An explicit language directive in Direct User Request Prose.
3. The primary natural language of the request-bearing clauses in Direct User Request Prose.
4. The previously established Interaction Language when Direct User Request Prose contains no usable natural-language signal.
5. English.

Do not use the written language of skill instructions or references, system/developer/project rules, AGENTS content, attachments, linked/quoted/pasted source material, host-injected context, tool or web output, code, commands, paths, filenames, URLs, identifiers, examples, fixtures, or terminology tables as evidence of the user's preferred Interaction Language. Direct User Request Prose may explicitly adopt a named source or a specific part of it as task scope, or explicitly designate that source's language as an output target. Scope adoption alone does not make the source's written language evidence of Interaction Language.

This section changes language inference and user-authorization inference only. It does not change the normal priority, applicability, or binding force of system, developer, safety, project, or repository instructions.

Core Concepts

• Current Plan: The single logical Plan state for one active planning task. It may exist only in the conversation, and an existing Plan is adopted only when Direct User Request Prose designates it for continued maintenance.
• Current Plan Document: The single persisted Plan document that carries the Current Plan. It is established by the Current Plan's first persistence or by Direct User Request Prose designating an existing Plan document for continued maintenance.

Use these defined terms unchanged in normative instructions. A non-Plan document is never the Current Plan Document, and search results, names, topics, similarity, or historical status establish neither identity.

引用资料加载规则

• 开始正式规划前读取 references/project-context.md，发现当前项目规则、知识入口、事实来源和验证入口。
• 规划包含源码改动点、Bug 修复、工具或系统开发时，读取 references/plan-decomposition.md。
• 需要确定分析对象范围和深度时读取 references/analysis-relevance-grading.md。
• 需要校准前置分析章节的写法和压缩方式时读取 references/pre-analysis-writing-guide.md。
• 当前范围存在真实方案分歧，或 Current Plan 已含 Decision-... 时读取 references/decision-record-rules.md；没有真实分歧时不加载，也不建立设计决策记录。
• 正式计划需要任务拆分时，通过 plan-decomposition.md 读取 references/task-decomposition-method.md。
• 输出或更新正式 plan 时读取 references/plan-output-template.md 和 references/plan-evaluation-criteria.md。
• 正式 Plan 的结构由模板负责；非中文受控显示值按本节语言规则由 SKILL.md 直接组合，不要求模板继续加载语言 reference。
• 需要处理文件路径展示和本地链接格式时读取 references/path-link-format.md。
• 创建、保存、更新或在上下文压缩/会话恢复后恢复 Plan 文档身份时，直接读取 references/plan-persistence.md。
• 按 Language Authority and User-Controlled Scope 先解析 Interaction Language，再为每个实际新建或写回的 Plan/文档分别解析 Output Artifact Language。既有维护对象在用户未明确指定该 artifact 语言时保持其主语言；新建交付物在用户未明确指定时采用 Interaction Language。只读输入 Plan/文档的语言只是 Source Artifact Language，不得覆盖任何输出语言。
• 面向用户的提问、说明、阻塞、评审结论和交付摘要使用 Interaction Language；正式 Plan 或被维护文档正文使用对应的 Output Artifact Language。每个输出表面默认只使用一种自然语言；不同表面使用不同语言不属于双语对照。
• “回复/说明/进度使用 X”只设置 Interaction Language；“Plan/文档使用 X”只设置被点名交付物；“翻译这份文档为 X”只切换该文档；未限定对象的“用 X 输出/全程用 X”设置本轮交互和新建交付物，但不自动翻译既有维护对象。
• 任意语言的普通同语言自然回复，以及只读审阅异语言输入但不生成非中文受控结构的场景，都不读取语言引用。
• 只有显式语言切换、翻译、双语或术语对照，对话语言与实际输出 artifact 语言不同，语言指令作用域无法唯一解析，或需要生成 zh-CN/en 之外的正式结构化表面时，才直接读取 references/output-language-policy.md。
• 输出或更新正式 Plan 时，直接读取 references/plan-output-template.md 与 references/plan-evaluation-criteria.md。
• 只有目标输出表面需要非 zh-CN 的受控 heading、label、status、pattern、正式 concept，或用户要求术语对照时，才直接读取 references/output-language-terminology.md；第三语言正式结构化表面固定同时读取 policy 与 terminology。命中后必须使用 terminology 的精确显示值，不得换用同义标题、缩写或近义机制词。
• 两个语言引用分别按自身条件加载；读取其中一个不触发另一个，也不通过 reference 间接加载 reference。
• 不一次性加载所有引用。只在当前阶段需要其职责时读取。

执行约束

• 只做计划、评审、Bug 分析和 Current Plan 维护，不修改代码、配置或资源文件；用户明确要求进入实现阶段时，将对应任务交给 cat-code。
• 任务分流：需求开发任务走开发计划主线；Bug 修复任务先定位问题，再给修复计划；纯评审请求以结论和改进建议为主。
• 先基于用户给定范围收敛任务边界；范围不清时先定义最小可行范围并标注假设。
• 只覆盖当前需求；只有直接依赖会改变方案范围、复用判断、风险或验证闭环时，才纳入最小必要关联范围，并在 In Scope 中显式说明。
• 需求不完善或有矛盾时，只对不会决定架构、行为或语义的非结构性信息建立最小假设，并显式写出假设及其影响。结构和行为等设计决策按当前规划责任与设计决策记录加载条件处理，不从 Skill 调用或默认配置推导用户确认。
• 默认先按“前置分析”中的共用原则建立与任务直接相关的事实模型，再进入规划；覆盖用户指定范围，并将影响方案的结论并入最终计划。
• 对源码改动执行范围发现和相关性分级时，读取 references/analysis-relevance-grading.md；在共用分析骨架上应用 Coding 的候选范围、正式等级、最低分析深度和输出义务。
• 对源码改动，若需要校准“前置分析”章节的写法、压缩方式与常见误区，读取 references/pre-analysis-writing-guide.md；非源码改动不加载该源码专项写作指南，但仍遵守本 Skill 的共用分析与正文压缩原则。正式非源码 plan 按目标对象自身结构和 references/plan-output-template.md 组织；普通非源码分析、解释或独立评审不因此套用正式 plan 模板。
• 对源码改动点，通过 references/plan-decomposition.md 使用唯一的 task-decomposition-method.md 生成 Task；非源码改动点使用 references/plan-output-template.md 定义的非源码修改卡片，混合计划逐项选择适用卡片。
• 优先复用现有框架、组件、状态机和网络链路；新增模块前先说明无法复用的原因。
• 源码和非源码规划都遵守当前项目适用的规则、边界和验证入口；通用 Cat 只负责发现和应用这些约束，不复制项目知识。新增对象、资源、配置或流程前，先检查当前项目是否已有可复用实现。
• 当前环境不能安全创建、编辑或验证的资源，记录其必要性、责任方或手动落地方式、依赖和验收证据；标记为外部补充项，不阻塞核心计划。
• Bug 任务优先输出：复现条件、实际/预期行为、根本原因和假设、最小修复路径、回归风险。
• 仅对实际包含源码实现的改动点，在涉及算法修改、关键接口调整或现有模块关键修改时，补充对应的文件、函数、接口、调用方、兼容策略和必要代码细节；非源码改动点按“改动类型与规则适用范围”处理。
• 在计划、评审或分析输出中处理文件路径展示文本或 Markdown 链接目标时，读取并遵守 references/path-link-format.md，本 Skill 不重复路径格式细节。

规划循环

• AI 在用户限定任务内连续完成事实调查、需求校正、分析重点判断、方案比较、技术决策、任务拆分和计划评估。
• 事实充分时，AI 在用户限定目标和范围内直接完成技术方案比较并形成当前设计，不逐项等待用户选择。
• 只有不可发现事实、用户定义的业务语义或主观偏好、重大风险接受、破坏性兼容取舍或范围扩张会决定结果时，才请求用户介入；先完成可发现事实调查，再提出最小必要问题。
• 用户介入分为补充事实和作出用户决策。事实缺口不包装成决策记录；需要用户作出决策的真实方案分歧使用 Decision Status: Open，并让受影响范围保持 Not Ready。
• 用户持续审阅 Current Plan，并对目标、业务价值和风险接受承担最终责任。
• Direct User Request Prose 明确修改已经建立身份的 Current Plan 所属需求、事实、设计、范围、就绪性或验证口径后，只重新分析受影响范围并更新同一 Current Plan。需要写回时仅维护已经建立的 Current Plan Document；不得根据反馈主题、仓库文件、其他任务文档或内容相似度推断 Plan 文档身份。
• 用户针对 Agent、向用户展示的推理摘要、回复语言、Skill 措辞、工具使用或工作流程提出疑问或不满时，默认将其视为仅在对话中处理的元请求（即针对交互本身的请求）。不得因此创建、更新、保存、同步或重写 Plan，除非同一轮的 Direct User Request Prose 明确要求对 Plan 进行相应操作，或明确改变了该 Plan 所涉及的需求、事实、设计、范围、就绪性或验证标准。同一轮同时包含元请求和针对 Plan 的反馈时，应回应元请求，并且只将明确针对 Plan 的部分写回。
• 未知事实、权威证据冲突、范围扩张或必须由用户定义的业务偏好不能被虚构；让受影响范围保持 Not Ready，并列出最小必要输入。

Current Plan 协作契约

• Current Plan 是活动规划任务中的权威快照和工作记忆，不是天然正确的事实来源。
• Current Plan 将关键分析、当前设计、必要的设计决策记录、任务、风险和验证保存在同一逻辑状态中，不拆成平行状态文档。
• Current Plan 只保留当前有效内容。普通修订过程、旧决策结果、失效方案、聊天脚手架和冗余历史不写入正文。
• 如需复盘历史，应读取聊天记录、版本历史或旧文件，并重新分析其与当前事实的关系；不能把模型上下文当作完整历史记录。
• 不确定性仍然真实存在时，记录当前未知项、失效条件和验证方式；不要为了文档干净把未知伪装成确定结论。

Plan Persistence

• Maintain one Current Plan Document per active planning task. Reuse the established Current Plan Document for continued work; create a new Plan document only when the Current Plan has no persisted document and persistence is requested, or when the user explicitly requests a new or separate Plan.
• Never overwrite an existing file to create a new Plan document.
• Before any Plan-document file action, read references/plan-persistence.md. If the Current Plan Document identity is ambiguous, do not write.

状态协议

正式 plan 使用两个正交状态：

• Document Status：Draft / Final Snapshot。
• Design Readiness：Ready / Partially Ready / Not Ready。

约束：

• 用户只要求规划、评审、分析、继续完善 plan 或仅提供参考文档时，停留在规划阶段，不进入代码修改。
• 用户明确要求实施指定 plan、Task 或边界明确的代码修改时，将对应目标交给 cat-code；该指令确定本轮实施目标，不写入 plan 状态，也不替代 Code 阶段的可执行性和施工门禁。
• 规划交付后停止；本 Skill 不实施代码。

输出语言与本地化

• 面向用户的对话表面使用按 Language Authority and User-Controlled Scope 解析出的 Interaction Language；每份实际新建或写回的 Plan/文档使用其 Output Artifact Language。只读输入的 Source Artifact Language 不接管任何输出表面。
• 每个输出表面默认只输出一种自然语言。只有用户明确要求翻译、双语或术语对照时，才在该表面并列多种语言。
• 固定协议、ASCII ID、代码、命令、路径、文件名、symbol 和 URL 保持原文。zh-CN/en 受控结构按 terminology 对应列逐字显示；第三语言按 policy 建立本次交付映射；普通说明正文按所属输出表面的语言自然表达。
• 语言选择不得改变 Plan 只规划不实施、单一 Current Plan、状态与授权分离、Open 范围不进入 Target/Task、后置评估不改变正文决策等既有规则。
• 第三语言普通同语言回复不附加质量说明；第三语言正式结构化交付按 policy 只说明一次未冻结术语与未成对回归的边界。

正式计划输出

• 以计划为主要交付物的草案、阶段计划、开发计划、修订计划、最终计划和写回 Markdown 的计划都属于正式计划输出；普通问答、单点分析、方案讨论片段和独立评审报告不强制套用计划模板。
• 输出正式计划时读取 references/plan-output-template.md；章节骨架、用户特殊要求的落位、设计决策记录和正文格式由该模板负责。
• 先完成正文，再读取 references/plan-evaluation-criteria.md 生成后置“方案评估与建议”；其字段、位置和合格标准不在本 Skill 重复定义。
• 用户明确要求 Plan 文档或完整 Plan 文档时，默认生成或维护本地 Markdown Plan；用户明确要求只在对话中展示时不存盘。用户只要求生成计划、制定方案、给出计划或等价内容型输出，且没有 Plan 文档、文件、路径、存盘或更新语义时，默认在对话中输出。Current Plan、Current Plan Document、具体 Plan 文档动作和目标路径按 Plan Persistence 及其直接加载的 reference 执行。独立评审报告或其他非 Plan 文档不使用该概念和 reference。

正文计划、用户特殊要求与后置评估的边界

• 正式计划输出分为两个阶段：先完成正文计划，再执行后置评估。
• 正文计划按 references/plan-output-template.md 的主干组织。
• 用户特殊要求只能影响对应正文内容或后置评估，不得随意替换模板主干章节。
• 用户特殊要求必须先分类再落位；目标章节和允许新增章节的位置读取 references/plan-output-template.md，本 Skill 不重复具体落位清单。
• 若只是计划质量判断，只能进入“方案评估与建议”。
• 文档操作相关特殊要求：按存盘、清理修订记录、最终版生成等规则执行，不新增正文评价章节。
• 独立评审报告相关特殊要求：若用户的主要交付物是评估、评审或复核报告，而不是正式计划文档，可输出独立评估报告，不强制套用实现计划模板。

弹性原则

• 工作流是正式规划的默认骨架，不是所有分析、核实和讨论请求的强制流水线；先根据用户当前目的与任务成熟度，判断应输出普通分析、探索性方案，还是正式计划。
• 用户仅要求分析、核实、解释或探索方向，或者任务目标尚不足以形成实施边界时，优先输出事实结论、未知项、候选方向和必要的下一步；可给出阶段性分析、探索性方案或候选草图，但不强制套用正式计划模板，也不补写缺乏依据的实施细节、正式 Task 或 Ready 结论。
• 对正式计划，允许根据任务复杂度裁剪、合并或扩展非核心章节，但不得与核心章节的固定要求冲突；在不丢失范围、分析结论、实现路径、验证和风险的前提下，允许调整输出结构与细节粒度。
• 复杂任务可以阶段性收敛，但每个阶段都必须有明确边界、当前状态和继续条件。
• 大型问题可以按边界或维度拆开分析；本 Skill 不扩展为完整项目管理、多人审批或资源排期系统。
• 对事实、范围、实施边界和验证保持刚性边界；对具体推理和求解方式保留模型发挥空间。

提问策略

• 只在缺失信息会实质改变目标、边界、行为、架构、风险接受或可实施性时提问。
• 优先完成现有证据允许的分析，再提出最小必要问题。
• 默认每轮聚焦一个或少量关键缺口；不要用大批泛化问题把分析责任转回用户。
• 无法落地时输出明确的待补充信息、受影响范围和可先行推进的部分。

需求校正

对于用户需求，一定要事先矫正。 用户的补充内容、中途反馈，或新的需求变更，都需要重新进行需求校正，确保任务目标和范围能够及时，准确的更新。 当用户表述不够准确，过于模糊，前后矛盾时，更需要认真的矫正需求，否则会对后续需求的分析造成困扰。

矫正原则：

• 识别冲突、歧义、遗漏，并做适当的补充、取舍、矫正。
• 选定实现口径，并说明选择理由与影响范围。
• 在必要的时候，及时查阅当前任务相关的最新成文计划，最近的沟通记录、展示过的思考记录、推理记录、分析过程和相关决策等，以获取最新的上下文信息，确保需求校正的准确性和完整性。

规划工作流（可部分裁剪）

整理任务目标

• 始终先整理任务目标；该步骤不得跳过。
• 整理用户原始需求或 Bug 描述，修正其中的歧义、遗漏和前后矛盾，使任务目标更准确、可执行。
• 如果是 bug，先明确问题所在，并针对问题设计修复计划。
• 如果是需求，则先写需求涉及模块的拓展方向，再设计开发计划。
• 按具体设计决策或改动单元标记玩法细节与一般系统设计；混合任务分别应用对应规则。

明确目标与范围

• 提取目标、目标类型、输入输出、触发条件和约束；生命周期、并发、网络、兼容、性能等维度只在任务实际涉及时补充。
• 定义 In Scope / Out of Scope。

Bug 定位与修复路径（Bug 任务优先）

• 先整理稳定复现条件（步骤、触发概率、客户端/服务端差异、输入条件）。
• 再定义实际行为与预期行为，定位偏差出现在哪个状态或调用链节点。
• 给出按优先级排序的根因假设，并标记对应证据和待验证点。
• 在不扩散改动范围的前提下，优先选择最小修复路径，并附回归风险与回退策略。

前置分析（默认执行）

• 对源码和非源码改动，都从用户明确指定、任务直接涉及或计划直接修改的对象中选择任务触点，建立与当前任务直接相关的事实模型。
• 从任务触点执行一次有界上收，检查能够共同解释、拥有、组织或直接约束这些触点的最小内聚分析单元；再只沿会改变方案范围、复用判断、风险判断或验证路径的必要直接关系扩展。具体证据问题闭合，或继续扩大不会改变方案时停止。
• 按分析对象对范围、设计、风险和验证施加的决策压力调整深度：背景对象只作排除说明，相关对象说明现有机制及关系，直接约束方案的对象完成功能、职责或规则分析，决定整体边界的对象单列聚焦分析并检查任务相关内容的交汇。
• 对源码改动，按 references/analysis-relevance-grading.md 把共用分析单元、直接关系和深度原则映射为 Coding 候选范围、Low / Medium / High / Very High 正式等级及最低输出义务。
• 对非源码改动，按文档、规则、配置、资源或工作流自身结构映射分析单元和直接关系；不机械补写代码状态、生命周期、调用链、算法或接口细节，也不得因此跳过有界上收、相关性深度或交汇分析。
• 将“前置分析”写入最终 plan 时，先满足与当前分析深度匹配的最低输出义务，再压缩为会影响方案边界、复用判断、风险判断和验证路径的事实、机制与约束结论；保留直接约束或决定方案的职责、规则、结构、状态、时序和交汇关系，不写无关背景、完整流程走读或阅读记录。

总体考量：

• 这是方案收敛、边界判断、复用判断与风险判断的重要参考，不得视为可省略的附属步骤。
• 先覆盖用户明确指定需要分析的内容。
• 若 AI 判断还存在强相关的分析对象或直接关系，可补充最小必要的关联分析，但避免无关扩散。
• 若用户未指定分析范围，则由 AI 根据任务触点、最小内聚分析单元和必要直接关系自行判断范围，并说明筛选依据。
• 在讨论过程中发现新的强相关内容时，立即补充对应的“前置分析”并更新 Current Plan；新增事实或决策只重新分析受影响范围，再同步当前设计及下游内容。
• 第 3 节聚焦“现状事实与约束结论”，第 4 节以后再展开“如何设计和修改”；避免把设计口径、猜测性推断或修改建议过早混进前置分析。

设计思路

设计思路是方案的核心部分，必须在方案主体生成之前完成。且后续的方案细则应当遵循设计思路，确保方案的一致性和可行性。 在持续的讨论和完善中，发现下游内容与设计思路冲突时：先复核设计思路；如果设计正确则修正下游，如果设计错误则先修订设计思路并同步受影响内容。 设计思路按实际需要可分为以下几类：整体设计、局部设计、关键流程设计、关键算法设计、关键架构设计、关键逻辑设计。

设计内容

• 使用“设计内容”统称 4.1 中需要预先定调的独立内容；具体标题统一使用“业务对象/机制 + ……设计”。
• 关键数据结构独立影响算法、所有权或兼容边界时，再形成关键数据结构设计。
• 每项设计内容说明设计结论、采用原因、适用范围，以及理解该设计所需的流程、职责、状态或边界。
• 当前设计思路形成后，AI 应主动检查其中是否存在需要进一步展开的核心内容或复杂设计，不等待用户额外提出。检查对象是已经确定的流程、算法、架构、数据结构、状态关系、关键逻辑或其他设计内容，不是重新分析现有系统中哪些对象复杂。
• 当某项当前设计只有概括性结论，尚不足以说明理解和实施该方案所需的关键关系、主要步骤、重要边界或实现影响时，主动补充必要细节；不需要进一步说明的内容保持简明。
• 关键流程、分支或调用关系实际影响方案理解和可行性时，说明其主要参与者、顺序、条件和结果；具体深度与表达形式由 AI 按项目类型、任务规模和复杂度判断，可使用文字、列表、表格、调用时序、伪代码或简图。
• 伪代码和流程图只在能明显减少关键歧义时使用；保持简明和可读性，不把所有实现细节预写进 Plan。
• 更细致且仍需说明的内容（比如：为了消除歧义或补充关键背景信息），放在随后的相关章节中补充。

组织与表达

• 简单任务允许只写一段设计；多个设计内容只有在需要独立解释时才拆分 4.1.x。
• 有调用、状态或共享边界时按真实先后排序并说明组合关系；没有直接关系时分别说明，不强行整合。
• 不按文件、Task 或验证项组织设计思路。

决策记录与下游边界

• 命中设计决策记录加载条件时，备选方案准入、决策责任和收敛规则按 references/decision-record-rules.md 执行；未命中时直接形成当前设计，不建立额外的方案治理机制。
• 存在 Open 决策或阻塞性事实缺口的范围不写成 Target，不生成正式 Task。
• 设计思路只呈现已经生效的一套当前方案；需要用户作出决策时，简短备选方案和推荐方案只保留在对应 Open 决策记录中。
• 在设计思路中保留关键算法、关键架构、关键逻辑的设计结论、选择原因和影响；精确参数、接口签名、逐文件修改与施工顺序下沉到 Target、算法、架构或 Task 章节。
• 不在设计思路中写 Task ID、文件卡片、依赖排序、Ready 或验证任务。

设计规划

• 构思设计思路前，一定要明确当前方案的应用场景和使用前提，以确保后续的设计思路具有针对性和可行性。
• 关于设计思路，应该参照当前的任务目标和范围，结合前置分析的结论，再形成可行的设计规划。
• 形成局部设计前，先从整体职责、状态流转、共享边界和现有扩展点进行检查，判断问题是否可以通过复用、微调或拓展现有架构或关键流程直接解决，避免一开始就在局部堆叠补丁。
• 存在改动简单、边界清晰，并且能够从根本上消除一类局部问题的架构或流程方案时，优先采用；只有整体方案收益不足、影响范围过大，或问题确实不涉及整体职责和流程时，才展开局部流程细则。
• 优先考虑架构不等于必须新增抽象、重构架构或扩大当前任务范围。
• 当前有效的设计思路要有确定性，并考虑好边界条件和约束条件，做到逻辑自洽；同时避免明显的过度设计（Over Design）和过度兜底。

整体设计和局部设计

由于任务目标本身可能是几个关联性比较弱的业务问题的组合，甚至是毫无关联的独立内容，所以整体设计和局部设计必须有效区分，不能强行整合，可以同时存在，也可以单独存在。 并且相关描述要简明易懂，具体的细节如果还需要展开和说明（主要是为了消除歧义），需要放在随后的章节架构细节 中补充

• 整体设计和局部设计如果有关联或是共享边界，必须在设计思路中明确说明，并且在必要时说明共享边界或组合关系。
• 整体设计和局部设计如果没有明确的关联或共享边界，则不要强行关联和整合。

关键流程设计、关键算法设计、关键架构设计、关键逻辑设计

对当前设计中已经确定的关键流程、算法、架构、逻辑或其他核心复杂内容，AI 应主动判断是否需要进一步细化，并说明选择原因、影响范围和理解当前方案所需的关键细节。具体需要补充哪些内容、细化到什么程度以及使用何种表达形式，由 AI 结合当前系统、架构、程序类型、项目规则、任务规模、风险和用户要求判断，不套用跨项目固定清单。 相关描述保持简明易懂；需要继续展开以消除关键歧义时，放在随后的 算法细节、架构细节 或其他适用章节中补充。 必须在设计思路中明确说明选择原因和影响范围。

这些设计，采用或借鉴外部算法、实现或架构时，说明名称、直接来源、采用部分和偏离点；融合多个来源时，简要说明各来源贡献与融合方式。

目标实现与专项细节

• 对源码改动点，把会影响方案实施的关键模块、接口、算法、状态和调用链下沉到足以理解当前方案的细节；对非源码改动点，写清准确位置、目标修改、保留/删除边界和验收方式，文字、顺序或键值本身影响行为时补充必要文本细节。
• 将用户给出的有效约束和注意事项落入对应方案边界。
• 计划包含当前环境不能安全创建、编辑或验证的资源时，写清手动落地步骤、依赖、验收方式及其对 Design Readiness 的影响；不把核心交付依赖伪装成非阻塞补充项。
• 更多细则参照其他已加载的 references 文档。

方案评估与建议

“方案评估与建议”是当前方案的一个校验流程。必须在方案主体生成后，再单独执行。 并按 references/plan-evaluation-criteria.md 中的相关规则分析当前的方案。

如果当前流程涉及方案生成、修改或完善，并且执行了完整的“方案评估与建议”：正式 plan 已写入本地文件时，在聊天窗口简要概述 方案评介、计划详细程度评估、当前问题 和 建议的下一步行动 的结论，不逐字重复正文；正式 plan 直接在聊天窗口输出时，只输出模板中的一份“方案评估与建议”。

方案思考迭代流程

每次方案分析、生成、完善、调整、核对或评审，都应结合任务复杂度、内容依赖以及方案阶段的逻辑先后关系决定是否分轮；简单且关联紧密的任务允许单轮完成，不为满足形式增加轮次。 存在多个弱相关问题、未闭合证据、相互依赖的设计内容或需要回退复核时，再拆分为必要轮次；每轮结束后，检查是否仍存在会改变方案的范围覆盖缺口、事实或证据缺口、未闭合的关键决策或下游冲突；不存在时停止追加轮次。

这里的“轮次”用于组织 AI 当前的思考重点，不等同于聊天回合、用户确认或固定的工具调用步骤。 分轮用于减少多个弱相关问题相互干扰，不限制完成当前判断所需的分析深度、关联信息或必要的回退调整。

• 方案生成流程应从明确任务边界和目标开始。
• 随后进行任务矫正和前置分析的准备工作。
• 进行前置分析后，结合任务目标和约束条件，形成设计思路。
• 当前设计思路形成后，主动检查其中的核心内容或复杂设计是否需要进一步细化，再形成后续方案细则。
• 细化当前设计时，如果发现支撑该设计的事实、约束或适用前提不足，先回到前置分析补充最小必要内容，再修订当前设计并同步受影响的下游内容；不要把补分析变成每次细化都要执行的固定步骤。
• 方案主体生成后，再进行独立的方案评估与建议。
• 如果方案本身只是探讨阶段，需要及时停止后续的完整方案结构生成，按“弹性原则”保留当前事实结论、未知项、候选方向和必要的下一步。避免做毫无价值的强制思考和推进，避免浪费时间。
• 每一轮思考和迭代，应当围绕一类主要工作内容组织，避免同时展开多个弱相关问题；为完成本轮目标，可以同步处理必要的关联问题，其余弱相关或独立内容留到后续轮次处理。

当任务需要多轮思考时，在宿主提供的过程更新位置简要显示当前轮次的关注重点、已执行的分析或核实、阶段性判断或已经形成的决定，以及下一步；如果宿主已经自动展示了等价信息，不重复输出。过程更新用于让用户掌握进度并及时纠正偏差，不要求逐步复述完整内部推理。

方案思考迭代的轮次划分、过程记录和中间推理不得写入最终方案正文。最终方案只保留长期有效的事实、设计思路、已形成的决定及其依据、方案细则、风险和验证等。“设计思路”属于正式方案内容，不属于这里排除的思考过程。

其它注意事项

细化专项

• 源码改动点存在关键算法要求时，写明主要步骤、参数、边界条件和失败回退；需要进一步消除实现歧义时，由 AI 自主补充伪代码、调用时序或简图。
• 采用或融合外部算法/实现时，记录直接来源、采用部分、偏离点或融合方式；不为项目内普通逻辑虚构外部来源。
• 实际涉及架构调整时，写明改动点、依赖、迁移策略与动机，并补充足以消除歧义的架构细节。
• 源码改动点存在算法修改或关键接口调整时，形成“变更清单”（文件/函数/接口签名/调用方/兼容策略），然后并入计划正文。

以上内容，具体位置按 references/plan-output-template.md 的章节骨架落位。

命名原则

规划新增或调整模块、类型、函数、参数等源码名称时，结合被命名对象自身承担的职责、能力边界和项目既有语义选择名称。

• 使名称清晰、简洁并能区分实际职责；避免使用含义过宽的泛称，也不要把调用条件、实现步骤或完整需求描述机械拼入名称。
• 不要仅按当前调用方、上层业务需求或有限使用场景命名；这些关系本身构成对象职责或稳定契约时，可以在名称中体现。
• 不为缺乏依据的未来复用刻意泛化名称；具体格式继续遵循目标语言和项目既有规范。

注释原则

规划新增或调整源码注释时，先读取当前项目适用的注释规则；项目没有更具体口径时，只规划名称、结构和接口不能直接表达的维护与排障信息。

• 按实际需要说明职责/原因、约束/边界、顺序/生命周期/生效条件、失败/清理/误用风险中的适用内容；接口、复杂流程、关键状态或配置不因对象类型而自动生成固定注释清单。
• 名称或结构能更清楚表达语义时，优先改进名称或结构；自解释代码和逐行复述默认不规划注释，具体语法、文件头和强制格式继续由项目规则决定。

任务与验证

• 对源码改动点按 references/plan-decomposition.md 的要求生成实现卡片、任务状态等；非源码改动点按 plan 模板生成修改卡片。
• 对于验证类内容，应优先使用项目中已有的验证方法、工具和流程。

质量检查清单

• 输出不空泛，关键点均落到具体系统或模块。
• 检查 4.1 设计思路 是否包含与任务复杂度相称的设计内容，子标题是否使用明确的“……设计”名称，设计是否与当前有效的 Decided 记录和 Target 一致，以及 Open 决策或阻塞性事实缺口是否错误进入 Target 或 Task。
• 检查章节、Target、Task 字段和后置评估是否匹配实际改动类型；只在出现对应源码维度时检查源码 Task、算法/接口、命名和注释要求。
• 命中设计决策记录加载条件时，按 references/decision-record-rules.md 检查准入、AI/User 决策责任、状态、当前结果和下游收敛。
• 需要用户介入时，检查“方案评估与建议”是否明确介入类型、原因、影响范围、最小问题和回复后的正文同步位置。
• 对所有前置分析，检查是否从任务触点完成有界上收和必要直接关系分析，是否按对象对范围、设计、风险和验证的决策压力选择深度，以及直接约束或决定方案的交汇关系是否形成结论。
• 对源码前置分析的 Coding 候选范围、正式等级、最低深度、明确对标内容和正文写法，再分别按 references/analysis-relevance-grading.md 与 references/pre-analysis-writing-guide.md 检查；对非源码正式 plan，按共用分析原则、目标对象结构、模板字段和适用的验证口径检查，普通非源码分析按当前交付目标检查。
• 检查当前设计形成后，是否主动识别并适当细化了其中需要重点说明的核心内容或复杂设计；已细化内容是否足以说明当前任务真正需要的关键关系、主要步骤、重要边界和实现影响，未命中的内容是否避免机械扩写。采用或融合外部方案时，再检查来源和采用关系。
• 检查关键内容是否被空泛动作词替代，并同时检查是否因追求形式完整而机械增加字段、伪代码、调用时序或图。
• Bug 任务必须包含复现条件、根因假设、最小修复点与回归风险。
• 包含至少一个主要风险及对应规避或回退措施。
• 所有关键假设均可追溯到对应的缺失信息。
• 检查能力受限资源是否记录了责任、落地方式、依赖、验收证据和 readiness 影响；仅在不影响核心目标与验收闭环时判为非阻塞。
• 涉及源码命名或注释时，检查名称是否反映对象自身职责并保留必要契约；注释是否只补充非显然的职责/原因、约束/边界、顺序/生效、失败/清理或误用风险；避免按有限场景机械命名、用注释补偿模糊结构、或对自解释代码逐行复述。
• 输出文件路径时完成 references/path-link-format.md 定义的质量门禁。