القائمة
维护 `.kflow/architecture/` 这份只记现状的系统地图，三种模式 update / check / backfill。触发：用户说"刷新 architecture"、"做架构检查"、"补这个模块的架构文档"、"方案和代码对得上吗"，或 feature 阶段需要先做架构动作。不写未来规划（走 k-roadmap）。
التثبيت باستخدام Codex أو Claude انسخ هذا Prompt والصقه في Codex أو Claude أو مساعد آخر ليراجع صفحة Skill ويثبّتها لك.
استنادا إلى تصنيف SOC المهني
feature 流程阶段 3——验收闭环：对照 design 核实现 + 回写 architecture / requirement / roadmap，最后产出 {slug}-acceptance.md。触发：用户说"功能写完了验收一下"、"做最后检查"、"准备 merge"、"出验收报告"。前置依赖 k-feat-impl 完成。
feature 流程阶段 1——为新功能起草 {slug}-design.md 作为后续实现和验收的唯一输入，拍板后抽出 checklist。触发：用户说"开始设计方案"、"写 design doc"、"准备实现 XX"，前提是已知道做什么、为谁、怎么算成功。
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-arch |
| description | 维护 `.kflow/architecture/` 这份只记现状的系统地图，三种模式 update / check / backfill。触发：用户说"刷新 architecture"、"做架构检查"、"补这个模块的架构文档"、"方案和代码对得上吗"，或 feature 阶段需要先做架构动作。不写未来规划（走 k-roadmap）。 |
开始任何判断或动作前，先读取 .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-paths.md。读取材料遵守.kflow/reference/shared-token-budget.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-paths.md + ARCHITECTURE.md 索引。architecture/ 下其他文档先看文件名 / frontmatter / 索引命中，只打开目标相关文档。
backfill / update 额外（详见 reference.md "读取清单"）：目标模块代码入口和核心文件 + 用户素材 + 相关 compound 沉淀（decision / explore / learning）+ 相关已有 feature 方案。compound / 历史 feature 先检索摘要，只读最高相关命中。update 专项：当前 doc 先读目录和要改章节；准备整体重写或发现跨节矛盾时再读全文。last_reviewed 之后的代码变更用 git log / diff --stat 先收窄，再读相关 diff。
check 额外（按子目标）：
design-internal / design-vs-code：方案 doc 先读 frontmatter / 目录 / 第 0-4 节相关小节；只有做完整一致性审计或发现矛盾时读全文 + 架构相关 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-paths.md），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-code