From kflow
Maintains `.kflow/architecture/` system map with three modes: update (sync with code changes), check (verify design-code consistency), and backfill (write missing module docs). Focuses on current state only, not future plans.
How this skill is triggered — by the user, by Claude, or both
Slash command
/kflow:k-archThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
开始任何判断或动作前,先读取 `.kflow/attention.md`;缺失则视为骨架不完整,提示先补齐或运行 `k-onboard`。
开始任何判断或动作前,先读取 .kflow/attention.md;缺失则视为骨架不完整,提示先补齐或运行 k-onboard。
.kflow/architecture/ 是项目"地图"——design 写方案前读它定位、issue-analyze 做根因时读它理解模块边界、新人读它知道系统大致长什么样。本技能是"起草 / 刷新 / 体检"三件事的统一入口。
architecture 是累积的、自给自足的系统地图,不是某次 feature 的详细方案,而是所有已落地 feature 沉淀下来的"系统现在长什么样"总图。读者打开应能看懂整体结构而不需要跳回历史 design。design 是临时增量稿,acceptance 把稳定下来的名词 / 编排 / 约束提炼回这里;design 文件归档,只在追究具体决策细节时翻。
只记现状不记计划——默认在 acceptance 跟着代码同步,必要时本技能主动 backfill / update。不写"未来会加什么层"、"下一步打算拆出 X 模块"——那些归 k-roadmap。用户说"我想重构成 X 架构"先走 roadmap 拆 feature,每次 acceptance 把实际达到的结构提炼回 architecture。
详略判据:够不够让读者不跳转就读懂系统——稳定、跨 feature 可见的那一层写全;模块内部循环、辅助函数、一次性实现决定不进来。
架构文档价值在准、稳、可查。AI 容易破坏这三点的几种问题:
AuthManager 协调 TokenService,代码里根本没 AuthManagerls -R共享路径与命名约定看
.kflow/reference/shared-conventions.md。文档结构模板、check 覆盖项、报告格式看同目录reference.md。
启动先判断模式三选一(不让用户选菜单):
| 用户说什么 | 模式 |
|---|---|
| "刷新 {某文档}"、"代码变了把架构 doc 同步"、"更新到最新" | update |
| "检查 design 自洽"、"方案和代码对得上吗"、"几份文档有没有打架"、"做架构体检" | check |
| "补一份架构 doc"、"这块模块一直没写档"、"把已经在跑的子系统结构写下来" | backfill |
判断不出问用户。用户说"我想重构成 X / 打算新做 Y 模块"——不是本技能的事,转 k-roadmap。
每次只跑一个模式,且只锁定一个目标:
backfill:给已存在但从没写过档的模块补一份(architecture/{type}-{slug}.md 或更新 ARCHITECTURE.md)update:按代码最新状态 + 用户素材刷新一份已有 doccheck:三个子目标之一
design-internal — 一份 design 内部一致性design-vs-code — design 与代码一致性architecture-folder-internal — architecture/ 多份文档间一致性为什么不一次做多件?起草时一次吐多份用户 review 不过来;检查时三个子目标视角和材料完全不同,同时做每边都不深。用户提多个目标让 TA 选一个。
Phase 1:锁定目标
Phase 2:读取材料
Phase 3:执行(backfill/update = 起草;check = 检查)
Phase 4:自查(backfill/update)或 输出报告(check)
Phase 5:用户 review
Phase 6:落盘(backfill/update)或 等用户拍板(check)
确认:模式 + 目标对象 + 范围。
范围不收敛就问用户收敛——一份 doc"全模块重写"往往意味着底下其实有多个独立子系统应该拆;一次检查覆盖整个 architecture/ 报告读起来抓不到重点。
共同必读:shared-conventions.md + ARCHITECTURE.md + architecture/ 下其他文档。
backfill / update 额外(详见 reference.md "读取清单"):目标模块代码入口和核心文件 + 用户素材 + 相关 compound 沉淀(decision / explore / learning)+ 相关已有 feature 方案。update 专项:当前 doc 全文 + last_reviewed 之后的代码变更(git log 粗扫)。
check 额外(按子目标):
design-internal / design-vs-code:方案 doc 全文 + 架构相关 docdesign-vs-code 再额外:与 design 第 2/3 节直接对应的代码architecture-folder-internal:用户圈定的几份 doc + 索引 + 顺藤摸到的被引用文档(不扩展到代码)backfill / update:按 reference.md "文档结构"写完整初稿不分批吐半成品——分批 review 用户看不到全局一致性,第 2 节描述的结构和第 4 节决策经常有跨节矛盾。
check:按 reference.md "检查覆盖项"(三个子目标各 6 类)逐条执行。每条不一致都要记可定位位置(file:line 或 design 第X节)+ 现象 + 影响 + 修复建议。
backfill / update:按 reference.md "自查清单"(7 条)就地跑一遍,发现问题在 review 前处理掉(删 / 标 TODO / 改写)。自查结果简短汇报——发现了就说,不要走过场。
check:按 reference.md "报告模板"输出完整报告(检查摘要 / 不一致清单带严重级别 / 观察项 / 一致性良好项 / 建议下一步)。
backfill / update:完整初稿贴给用户 review。 check:报告给用户,等确认结论。本技能不替用户拍板。
backfill:
architecture/{type}-{slug}.md(命名规则见 shared-conventions.md 第 0 节),frontmatter status: current、last_reviewed 填当天architecture/{type}/、去掉文件名前缀、同步改 ARCHITECTURE.md 链接;搬迁清单在 Phase 5 一并 reviewARCHITECTURE.md 加新文档引用——backfill 必定要加,否则写了没人会读;改动同样 review,不偷偷改update:覆盖已有文件,last_reviewed 更新当天;结构性改动大时文末 变更日志 节加一条;ARCHITECTURE.md 只在 scope/summary 影响索引描述时更新。
check:不落盘结束。用户可能基于报告决定触发 backfill/update——那是下一轮的事。
file:line;锚不到标 TODO: 待确认。模块在代码里还没写就不该走 backfill —— 那是规划转 k-roadmap共通:
backfill / update 额外:
doc_type: architecture / status / last_reviewed)file:line 锚点或标 TODO: 待确认ARCHITECTURE.md 已加链接(或用户明确决定暂不加)变更日志 条目check 额外:
| 方向 | 关系 |
|---|---|
k-req 配合 | req 写"为什么有这个能力"、本技能写"用什么结构实现";frontmatter implements 反向链到 req slug |
k-feat-design 上游 | design 写"本 feature 和哪块架构对接"时读本技能产出的 doc;design 写完可触发 check 体检 |
k-feat-accept 下游 | 验收阶段实际去更新本技能产出的 doc(acceptance 自己归并,不回调本技能);想确认实现 vs design 对得上时触发 check design-vs-code |
k-decide 配合 | 拍板架构决策后,update 模式把引用补进相关 doc 第 4 节 |
k-issue-analyze 读者 | 根因分析读本技能 doc 定位模块边界 |
k-onboard 创建者 | onboard 建 ARCHITECTURE.md 占位,之后由本技能填实 |
k-roadmap 配合 | architecture 记现状、roadmap 记规划。roadmap 起草读本技能 doc 理解现状但不改它;目标态架构归 roadmap |
backfill / update:
ARCHITECTURE.md 索引——写了没人能发现{type}-{slug}.md——分组规则形同虚设check:
architecture-folder-internal 顺手读代码——那是 design-vs-codenpx claudepluginhub kunbo928/kflowCreates, edits, and optimizes skills for Claude Code, including drafting, evaluating with test prompts, iterating on performance, and improving skill descriptions for better triggering accuracy.