القائمة
feature 流程阶段 1——为新功能起草 {slug}-design.md 作为后续实现和验收的唯一输入，拍板后抽出 checklist。触发：用户说"开始设计方案"、"写 design doc"、"准备实现 XX"，前提是已知道做什么、为谁、怎么算成功。
التثبيت باستخدام Codex أو Claude انسخ هذا Prompt والصقه في Codex أو Claude أو مساعد آخر ليراجع صفحة Skill ويثبّتها لك.
استنادا إلى تصنيف SOC المهني
维护 `.kflow/architecture/` 这份只记现状的系统地图，三种模式 update / check / backfill。触发：用户说"刷新 architecture"、"做架构检查"、"补这个模块的架构文档"、"方案和代码对得上吗"，或 feature 阶段需要先做架构动作。不写未来规划（走 k-roadmap）。
feature 流程阶段 3——验收闭环：对照 design 核实现 + 回写 architecture / requirement / roadmap，最后产出 {slug}-acceptance.md。触发：用户说"功能写完了验收一下"、"做最后检查"、"准备 merge"、"出验收报告"。前置依赖 k-feat-impl 完成。
feature 流程阶段 2——按 {slug}-checklist.yaml 里 design 切好的 paradigm 维度 steps 推进，每步具体改哪个文件由 implement 自决，写完用统一格式汇报。触发：用户说"方案确认了开始实现"、"按方案写代码"、"开工"。前提是 design 已 approved 且有 checklist。遇到方案外情况要回方案谈不要硬冲。
issue 流程阶段 2——读 report + 读代码定位根因、评估风险，给用户 2-3 个修复方案让 TA 拍板。这一步不改代码。触发：用户说"分析这个 bug"、"找根因"、"定位问题"，且已有 {slug}-report.md。
issue 流程阶段 3——按已确认根因和方案定点修复、验证、写 {slug}-fix-note.md 落档。两个入口：标准路径从 analyze 来，快速通道从 report 直接来。触发：用户说"开始修 bug"、"按分析修"、"动手改代码"。只动方案声明的文件，不顺手优化。
把新仓库或有零散文档的仓库接入 kflow 体系——两条路径自动判断：空仓库从零搭骨架，已有文档走审计 + 迁移映射——然后释放技能文件和跨平台入口（AGENTS.md，可选 CLAUDE.md）。触发：用户说"在这个项目里用 kflow"、"搭 kflow 结构"、"初始化 kflow"、"迁移到 kflow"。
| name | k-feat-design |
| description | feature 流程阶段 1——为新功能起草 {slug}-design.md 作为后续实现和验收的唯一输入，拍板后抽出 checklist。触发：用户说"开始设计方案"、"写 design doc"、"准备实现 XX"，前提是已知道做什么、为谁、怎么算成功。 |
开始任何判断或动作前，先读取 .kflow/attention.md；缺失则视为骨架不完整，提示先补齐或运行 k-onboard。
这一阶段的产出是一份方案文件 {slug}-design.md，加上从中抽出的行动清单 {slug}-checklist.yaml。这两份东西后面会被两个阶段消费——implement 照着推进、acceptance 照着核对，所以这里写错或写漏，下游就跟着错。
共享路径和命名约定看
.kflow/reference/shared-paths.md。读取材料遵守.kflow/reference/shared-token-budget.md，先用索引 / 检索 / 相关节收窄，不批量读历史正文。本阶段一般 feature 目录已经由 brainstorm 创建好了；没有的话在这一步建。
本阶段有三个入口：
{slug}-intent.md），直接进"流程"一节走完整起草。{slug}-intent.md 就结束本轮，等用户填完再回来。roadmap / roadmap_item 两个字段，同时回写 items.yaml 把对应条目 status 改为 in-progress、feature 填为 feature 目录名。详见下文"从 roadmap 条目起头"。触发：用户想自己写一份半成品方案（{slug}-intent.md）作为后续 design 的输入，但不想手动建目录。
动作：
和用户快速对齐两件事——一句话需求概要 + 敲定 slug（小写字母、数字、连字符；user-auth、export-csv 这种）。日期取当天（frontmatter 用 currentDate 即可）。feature 目录命名是 YYYY-MM-DD-{slug}。
创建 .kflow/features/{YYYY-MM-DD}-{slug}/ 目录。
写一份空的 {slug}-intent.md 作为草稿骨架，内容就是下面这段：
---
doc_type: feature-intent
feature: {YYYY-MM-DD}-{slug}
status: draft
summary: {一句话需求，AI 按和用户对齐的结果填}
---
# {slug} intent
## 背景 / 为什么做
（一句话就够）
## 大致怎么做
（100 字左右描述想法，含关键步骤 / 数据流）
## 相关数据结构 / 类型
（贴相关 types、接口签名、或指向代码位置）
## 已知不做 / 待定
（可选：明确的边界或自己也没想清楚的地方）
告知用户"骨架已建好，填完后再来找我，我基于 intent 写正式 design"，然后本轮结束，不继续推进 design 流程。
为什么在这里停？intent 的价值就是让用户离线思考、把脑子里的东西落到纸面。AI 继续问会把 intent 模式退化成 brainstorm，失去意义。
触发：用户说"开始做 roadmap 里的 {子 feature}"或指向 items.yaml 里某条 planned 条目。
{roadmap-slug}-roadmap.md 和 {roadmap-slug}-items.yaml：
status: planned + depends_on 前置全 done，否则停下来报告k-roadmap update 改，不要在 design 里偷偷绕开YYYY-MM-DD-{roadmap 条目 slug}，不另起roadmap / roadmap_item 两字段status: approved 同时回写 items.yaml：对应条目 status: in-progress + feature: YYYY-MM-DD-{slug}，用 validate-yaml.py 校验完整衔接协议看 .kflow/reference/shared-roadmap-feature.md。
design 只管"编排-计算分离"里的编排那一侧：这次 feature 在名词层和编排层的现状与变化。计算层细节（具体怎么写、改哪些函数、测试怎么搭）归 implement。
写三类东西，名词层和编排层都用"现状 → 变化"两段式：
外加一个固定结构健康度环节（第 2.5 节）：评估即将被改动的文件是否偏胖 / 职责混杂、以及新文件要落进的目录是否摊平，决定是否在实现前先做"只搬不改行为"的微重构（拆文件 / 重组目录）。即使结论是"不做"也要在 design 里显式写出来——否则 AI 默认会持续往胖文件里塞代码、往拥挤目录里加文件。这一节随整稿一起进整体 review，不单独走确认。
判据：换一种写法名词层或编排层会变得不同 → design 的事；换一种写法只是"代码不那么好看 / 函数拆法不同 / 测试用了别的 framework" → implement 的事。
不写改动文件清单、函数级落点、测试代码、库选型细节——design 阶段还没读完相关代码，预测多半会回头改。implement 拿到 design 后才扫现状决定。
读者打开 {slug}-design.md 是想 5 分钟内抓到要点，不是逐字精读。具体做法：
碰到"用户没说清的角落"默认停下来问，不自己挑一个填上去。具体：
回答："如果想把它拔掉，要拔哪些地方？" 答不出说明边界没想清楚，feature 一上线就变成拆不动的既成事实。
落到挂载点清单（第 2.3 节）。判据：删掉这一项，feature 在用户/系统视角是不是就消失了？是→列，否→不列。详细 ✅/❌ 例子和写法看 reference.md。这清单顺带帮你发现自己有没有不小心往太多地方插桩——真挂入点越多代表耦合越散，是个信号。
前置 gate：需求输入至少含 用户目标 / 核心行为 / 成功标准 / 明确不做 四项（来源 intent / brainstorm / 对话）。缺了补；用户自己说不清就回退到 brainstorm。
必做 4 条：
{slug}-design.md / {slug}-intent.md / {slug}-brainstorm.md：
status=draft 各节基本完整 → 跳到本流程"5. 整体 review"status=approved → 别默认覆盖，问用户接着改还是另起 slug.kflow/ 发现可用目录和文档类型，按类取用；默认只读 L0/L1 信息，命中后再读相关节：
architecture/ → 读 ARCHITECTURE.md + 索引 + 相关子系统 doc，关注名词复用和流程级约束requirements/ → 有对应 req：frontmatter requirement 填 slug，读"用户故事 / 边界"两节；新能力首次出现 → 触发 k-req draft 起草愿景 req，frontmatter requirement 填新 slug；纯重构 / 技术债留空compound/ → 用 search-yaml.py --dir .kflow/compound 搜相关 decision / explore / trick / learning；默认只读最高相关 1-3 个命中，命中冲突 decision 必须正面回应features/ → 搜历史 design 有无同类 feature 可参考；先读 frontmatter / summary / 相关节，不批量读全文按信号触发 3 条（没信号跳过）：
.kflow/reference/code-dimensions.md 列偏离点；无信号写"走默认档位"详细规则看 .kflow/reference/shared-archive.md。
动笔写名词层 / 编排层前，先回答：这次要加的东西在项目整体结构里属于哪儿？
代价：放错了模块就变"什么都装的筐"；新建平行实现就有几个版本同存。
结论写进第 1 节"决策与约束"。涉及新建模块或跨模块接口时同步写进第 4 节，提示在 ARCHITECTURE.md 加指向。
AI 默认翻车的姿势是不思考就往眼前最顺手的文件里加。
按 reference.md 模板写第 2 节四个子节（2.1 名词层 / 2.2 编排层 / 2.3 挂载点 / 2.4 推进策略）。重点提示：
"现状"必须指向代码位置，不能想当然——读者要靠它判断"变化"是否合理
编排层开头一张 mermaid 图建 mental model
挂载点按"删了它 feature 是否消失"判据，3-5 条为正常区间
推进策略按 paradigm 维度切片（编排骨架 → 计算节点 → 持久化 → 集成测试与全量回归），不下沉到 file:line。前面各步由 implement 按严格 TDD 落单元测试，最后一步专门落集成测试（真实环境）+ 全量回归
第 2.5 节"结构健康度与微重构"是固定步骤——按 reference.md 写作要求评估两类对象：要改的文件（文件级）+ 要落新文件的目标目录（目录级）。评估前先查 compound 已有 convention（关键词围绕"目录组织 / 文件归属 / 命名约定"），命中就直接照办。结论三选一：
选择 2 / 3 时给出"搬什么 → 搬到哪 → 怎么验证行为不变"的具体方案，落进 checklist 作为第 1 步且独立验证退出，再开始 feature 主体
重组目录时多问一步：是稳定模式还是一次性整理——稳定模式（如"自定义业务组件统一放 components/custom/"，未来其他 feature 也该遵守）就在 2.5 末尾加"建议沉淀的 convention"段，提示用户 implement 跑通后走 k-decide 归档；一次性整理（只是这个目录碰巧挤了）就只搬不归档。design 阶段不直接归档——方案还没真跑过，留钩子给 implement 后再决定
design 只做安全的微重构，边界严格守住："只搬不改行为"——文件级靠 IDE rename / move + 编译器校验，目录级靠纯文件移动 + import 路径更新 + 编译器校验。一旦涉及改函数签名 / 改返回值结构 / 改调用关系语义 / 模块拆合，就超出 design 范围：写进第 2.5 节末尾的"超出范围的观察"里提示用户"建议后续走 k-refactor 处理"，不阻塞本 feature、不作为前置依赖。是否真去做、什么时候做由用户在 feature 之外决定
第 2.5 节随整稿一起 review，不单独确认——和功能方案打包给用户一次过，避免拆成两轮把节奏拖长
按 reference.md 模板补齐剩余节（第 0 / 3 / 4 节）。初稿 frontmatter status: draft。
整稿成型后才交给用户看，不分批 review——分批用户只看到局部，发现不了"第 1 节范围跟第 2 节变化对不上"这种跨节问题。
第 3 节"验收契约"提示：每条写成"输入 / 触发 → 期望可观察结果"，覆盖正常 + 边界 + 错误。不写测试代码 / framework / mock。
发一次整体 review 提示（提示词在 reference.md 第 5 节）。用户提意见就改，反复直到放行，把 status 从 draft 改 approved。
方案确认后从 {slug}-design.md 抽出 steps + checks 落到 {slug}-checklist.yaml。完整格式、提取规则、典型节奏看 reference.md 第 3 节。
落盘后 python .kflow/tools/validate-yaml.py --file {path} --yaml-only 校验。
按下文退出条件核对，引导用户进入阶段 2。
用户整体 review 通过，并且：
doc_type / feature / status=approved / summary / tags），requirement 字段已对齐{slug}-checklist.yaml 已落盘并通过 validate-yaml.py 校验status: in-progress + feature 填上）