메뉴
[project] 架构演进同步器。把已归档 change 的 DESIGN.md §9 架构沉淀 同步到项目级文档（CONTEXT.md + ARCHITECTURE.md）。只读 §9，只 patch 文档，不动业务代码。 GitNexus MCP 可用时用于检测代码与文档之间的偏差（新抽象未入索引、ADR 与实际代码不一致）。 Use when 用户说"同步架构/整理沉淀/sediment/evolve/架构演进/同步 CONTEXT"，或每月/每季度批量同步时。
Codex 또는 Claude로 설치 이 Prompt를 복사해 Codex, Claude 또는 다른 어시스턴트에 붙여 넣으면 Skill 페이지를 검토하고 설치를 진행할 수 있습니다.
SOC 직업 분류 기준
| name | flow-evolve |
| description | [project] 架构演进同步器。把已归档 change 的 DESIGN.md §9 架构沉淀 同步到项目级文档（CONTEXT.md + ARCHITECTURE.md）。只读 §9，只 patch 文档，不动业务代码。 GitNexus MCP 可用时用于检测代码与文档之间的偏差（新抽象未入索引、ADR 与实际代码不一致）。 Use when 用户说"同步架构/整理沉淀/sediment/evolve/架构演进/同步 CONTEXT"，或每月/每季度批量同步时。 |
| paradigm | philosopher |
| trigger | [{"pattern":"同步架构|整理沉淀|sediment|evolve|架构演进|同步 CONTEXT|同步文档|升级 CONTEXT|升级架构文档","context":"用户想把多个已完成的 change 的架构沉淀合并到项目级文档"},{"pattern":"每月同步|季度同步|里程碑后同步|CONTEXT 失准|架构滞后","context":"周期性架构同步，或发现 CONTEXT.md 与代码实际不符"}] |
A 前缀表示 Architecture / 横向命令，不属于任何 change，不写 CHANGE.md / REQUIREMENT.md。直接产出沉淀同步报告 + patch 项目级文档。
| 工作流 | 干什么 | 何时跑 | 改 ARCHITECTURE.md 哪段 |
|---|---|---|---|
| flow-evolve（本文） | 把 change 级沉淀单点 append 到项目级文档 | 每月 / 每季 批量 | 仅 append ADR 列表 / 跨模块契约段 / 修订历史 |
| flow-architect | 重写 / 大改 ARCHITECTURE 全篇 | 首次建立 / 重大重构 / ADR 重审 | 任何段都可改 |
如果 flow-evolve 过程中发现需要"改架构"（某条 ADR 应该 deprecated / 依赖规则该改）→ 停下来，提示用户跑 flow-architect。
STATE.md last_evolve_at 距今 > 60 天：flow-go 路由时会主动提示STATE.md（读 last_evolve_at 决定扫描范围）.specs/CONTEXT.md（patch 目标 · rules 层）.specs/ARCHITECTURE.md（如存在，则同时是 patch 目标 · structure 层）.specs/archive/<YYYY-MM-DD>-<change-id>/DESIGN.md（已归档 change 的设计文档 · 只读 § 9 段）.specs/<active-id>/DESIGN.md（当前活跃 change 也算，但仅在 flow-dev 完成 / flow-integration 之后才纳入）.specs/CHANGELOG.md（看 change 元信息，做 cross-check）读 STATE.md：
last_evolve_at: <YYYY-MM-DD> → 只扫该日期之后归档的 change.specs/archive/* 的 DESIGN.mdlast_evolve_promoted: [<list>] → 这些 change 的 § 9 已处理过，跳过输出范围声明（见 references/EVOLVE.md 模板）。
如果范围为空 → 直接告诉用户"无新沉淀可同步，CONTEXT.md 已最新"，结束。
对范围内每个 change：
^## 9\. 架构沉淀建议Token 预算：每个 change 的 § 9 大约 30-80 行。一般 5-10 个 change 一次同步。超过 15 个建议拆两次跑。
按五类聚合（跨 change 合并）：
| 路径 | 能力 | 来自 change | 复用建议 | 跨 change 冲突？ |
|---|---|---|---|---|
src/lib/cache.ts | LRU 缓存 | add-cache-layer | 沿用 | — |
src/utils/date-fmt.ts | 日期格式化 | add-notifications | 沿用 | ⚠️ 与既有 src/utils/date.ts 重复 |
冲突检测必跑：每条新抽象 grep CONTEXT.md「既有抽象索引」段是否已有同类 → 有则标 ⚠️。
GitNexus 路径（可选）：对每条新抽象调用 gitnexus_context(name="<抽象名>")，验证符号在代码中确实存在且仍活跃（不是已删除的过时条目）。如果符号不在 GitNexus 图中 → 标 ⚠️ "代码中可能已不存在"。
| 决策 | 取值 | 来自 change | 影响范围 | 与现 CONTEXT 冲突？ |
新增 API：
新增事件：
Schema 变更：
| 包 | 版本变动 | 来自 change | 是否替换 |
新增禁动：
解禁：
按五类逐项问用户：
🟢 候选 1/N · 新增抽象 · src/lib/cache.ts
能力：LRU 缓存封装
来自：add-cache-layer（archive/2026-04-12）
建议：append 到 CONTEXT.md「既有抽象索引」段
AI 检测：与 CONTEXT 现有内容无冲突
选项：
✅ 接受 promote
❌ 跳过（理由：例如临时用，不长期保留）
✏️ 编辑后 promote（你写新版本）
请回复：1 / 2 / 3
每条等用户回复后才进下一条。严禁一次性 batch promote 全部。
冲突标 ⚠️ 的项额外问：
⚠️ 冲突候选 · 新抽象 src/utils/date-fmt.ts vs CONTEXT 现有 src/utils/date.ts
两者能力重叠（都是日期格式化）。
选项：
✅ 替换 — 用 date-fmt.ts 替换 date.ts
✅ 共存 — CONTEXT 索引同时列两个，注明用途差异
❌ 跳过 — 不 promote 新的
✏️ 编辑后定夺
请回复：1 / 2 / 3 / 4
收集所有用户批准的项，生成两份 patch（项目有 ARCHITECTURE 则两份都生）。
见 references/EVOLVE.md 模板 §5.1。
见 references/EVOLVE.md 模板 §5.2。
两者分工：
✅ 即将应用的 patch（CONTEXT 共 N 条，ARCHITECTURE 共 M 条）：
[先贴 CONTEXT patch]
[再贴 ARCHITECTURE patch · 如有]
确认应用？
1. ✅ 应用两边
2. ⏸️ 暂存 patch 为 .specs/evolve/<YYYY-MM-DD>-EVOLVE-PATCH.md，我手动合
3. ✅ 只应用 CONTEXT
4. ✅ 只应用 ARCHITECTURE
5. ❌ 取消
安全要求：
cp .specs/CONTEXT.md .specs/CONTEXT.md.bak-<YYYY-MM-DD>cp .specs/ARCHITECTURE.md .specs/ARCHITECTURE.md.bak-<YYYY-MM-DD>（如存在）edit 工具按段 append / update（不要整文件 rewrite）<!-- flow-evolve YYYY-MM-DD: from <change-id> -->^### ADR-\d+ 取 max + 1）.specs/evolve/<YYYY-MM-DD>-EVOLVE.md见 references/EVOLVE.md 模板 §7.1。
STATE.mdlast_evolve_at: <YYYY-MM-DD>
last_evolve_promoted:
- add-cache-layer
- add-bg-jobs
# ... 本次涉及的所有 change-id（无论是否被 promote，只要扫过就记）
.specs/ 内项目级文档，禁止改 src/ / tests/ / package.jsoncp 备份STATE.md 的 last_evolve_at 决定扫描范围.specs/evolve/last_evolve_at + last_evolve_promoted 已更新项目级架构梳理师。建立或重构 `.specs/ARCHITECTURE.md`，包含模块图、ADR 列表、跨模块契约、依赖规则和容量边界。优先使用 GitNexus MCP 提取模块社区、依赖关系和 API 路由，grep 作为回退。Use when 用户说"建立架构/架构梳理/重构架构/architect/重审 ADR/画架构图"，或项目首次使用 flow-x 且需要项目级架构文档时。不属于任何 change，不写 CHANGE.md。
变更提案生成器。把用户的模糊想法通过反问澄清为一份变更提案 CHANGE.md，自动生成 change-id，检测架构级变更（优先使用 GitNexus MCP impact 分析），前端项目预选视觉调性，判定影响面并给出路径建议。Use when 用户说"我想做/加/实现/设计某事"且无活跃 change 时，或需要发起新变更提案时。
技术设计师。把 REQUIREMENT.md 转化为可执行的技术设计 DESIGN.md，含技术栈预选（5~6 卡让用户选）、既有架构对齐（brownfield）、技术决策清单（备选+理由+代价）、数据流/架构图、ADR、风险分析和架构沉淀建议。优先使用 GitNexus MCP 定位既有模块和抽象，grep 作为回退。Use when 用户确认 REQUIREMENT.md 后需要进入技术设计阶段，或需要技术选型/架构评审时。
单任务开发执行器。在 fresh context 中按 TDD（RED→GREEN→REFACTOR）执行 TASK.md 中的一个任务，优先使用 GitNexus MCP 搜索既有抽象和做变更影响分析，grep 作为回退。Schema 变更生成可逆迁移，破坏性变更走影响分析+反问协议，提交前跑 diff 边界 verify 和 6 维 self-review。Use when 用户说"执行 T<NN>/跑 T<NN>/do T<NN>/继续"，或需要实现 TASK.md 中的某个任务时。
flow-x 统一入口 Orchestrator。解析用户意图，自动匹配阶段，执行 Artifact Preflight Gate，估算 Token 预算，加载必要规则与工件，路由到对应子 skill 执行。支持 GitNexus MCP 可用性检测，GitNexus 可用时子 skill 自动优先使用 MCP 工具。Use when 用户说"开始做某事/继续/审查/测试/设计/换风格/健康检查/扫描代码/架构梳理"等任何与 flow-x 流程相关的意图，或需要自动管理 change 生命周期时。
[project] 代码库健康巡检器。只产健康报告 + 改造建议清单，不直接改代码。 支持工具路径（brooks-lint / jscpd / knip 等）、GitNexus MCP（语义级未用导出/循环依赖/跨模块检测）和内置 AI 回退三种模式。 Use when 用户说"健康检查/health/体检/技术债扫描/巡检/代码质量检查"，或周期性/里程碑前/接手陌生项目时。