Menu
feature 流程阶段 1——为新功能起草 {slug}-design.md 作为后续实现和验收的唯一输入，拍板后抽出 checklist。触发：用户说"开始设计方案"、"写 design doc"、"准备实现 XX"，前提是已知道做什么、为谁、怎么算成功。
Installer avec Codex ou Claude Copiez ce prompt, collez-le dans Codex, Claude ou un autre assistant, puis laissez-le vérifier la page du skill et l'installer pour vous.
Basé sur la classification professionnelle 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 填上）