diff --git a/.claude/skills/sm-flow/SKILL.md b/.claude/skills/sm-flow/SKILL.md deleted file mode 100644 index be77fd4..0000000 --- a/.claude/skills/sm-flow/SKILL.md +++ /dev/null @@ -1,83 +0,0 @@ ---- -name: sm-flow -description: OpenSpec-first 的结构化工程开发协议层 harness。编排 OpenSpec 的完整生命周期，通过阶段、门控、人类对齐和长期记忆，约束 agent 以正确的顺序、条件和标准使用 OpenSpec。用户想把粗略想法、issue、PRD 或已有 research 推进为准确 OpenSpec change，并通过 OpenSpec apply 实现、验证、归档时使用。 ---- - -# SM Flow - -SM Flow 是一个**协议层 harness**——编排 OpenSpec 的完整生命周期。它通过阶段、门控、人类对齐和长期记忆，约束 agent 以正确的顺序、条件和标准使用 OpenSpec。 - -sm-flow 会自动维护 `devflow/` 目录作为项目长期记忆。用户不需要手动管理它，sm-flow 会在流程中自动读取和回填。 - -## 四层架构 - -``` -sm-flow → 编排层（harness）：阶段、门控、产物约束、人类对齐 - OpenSpec → 执行引擎：propose/apply/archive 的能力提供方 - devflow/ → 记忆层：为编排层提供上下文，接收执行结果的回填 - code → 实现结果：apply 的产出 -``` - -- OpenSpec 是唯一执行真理源：apply 阶段只能基于 OpenSpec 执行，不能绕过 OpenSpec 直接写代码。 -- devflow 是上下文真理源：术语、历史决策、验收记录来自 devflow，用于增强 OpenSpec，不替代 OpenSpec。 -- 如果 devflow 和 OpenSpec 冲突，先汇报冲突、让用户确认、修正 OpenSpec，再继续执行。 -- propose 阶段产出的 OpenSpec 默认为 **Draft OpenSpec**：它是澄清和审计对象，不是 apply 的执行许可。 -- 只有通过 commit 检查后的 OpenSpec 才是 **Committed OpenSpec**；apply 只能执行 Committed OpenSpec。 - -## 核心规则 - -以下 6 条是硬约束，违反即流程失败。其余约束按阶段定义在 `references/phase-contracts.md`。 - -1. **OpenSpec 是唯一执行真理源**。apply 阶段必须读取 Committed OpenSpec 文件作为执行依据；对话中的描述不等于产物。Draft OpenSpec 是讨论对象，不是执行许可。 -2. **不得跳过 context**。生成 OpenSpec 前，必须先读取相关 devflow 上下文（glossary、ADR、历史项目）。 -3. **不得跳过 grill**。即使需求看起来很清楚，至少解决三个高价值澄清或验证问题。 -4. **不得跳过 commit**。进入 apply 前，Draft OpenSpec 必须通过 commit 检查成为 Committed OpenSpec。 -5. **冲突必须先分类再处理**。OpenSpec 不准（规格遗漏）→ 修正 OpenSpec；代码偏离（实现偏差）→ 修正代码；不确定或涉及设计方向 → 暂停并等待用户确认。 -6. **子 skill 必须显式调用**。每个阶段指定的子 skill 必须显式调用；如果子 skill 不存在，流程失败，不得静默跳过或降级执行。 - -每个阶段的过程约束（question pool、one-at-a-time、cross-artifact 对齐、冲突回写等）和质量约束（可观测产出要求）见 `references/phase-contracts.md` 中对应阶段的退出条件和 checkpoint。 - -## 用户命令 - -| 命令 | 用户意图 | harness 内部行为 | -|---|---|---| -| `/sm-flow` | 完整流程 | clarify → context → propose → grill → specify → audit → commit → apply → archive | -| `/sm-flow explore` | 先想想 | 带上下文的探索模式 | -| `/sm-flow apply` | 只执行 | 检查 commit gate → apply | -| `/sm-flow archive` | 收尾 | 回填 devflow + 归档确认 | - -用户也可以用自然语言指定从某个阶段继续，例如"ops-message-support 的 grill 已经做完了，继续"。harness 识别意图后，自动补做最小前置检查，然后从指定阶段继续。 - -## 首次加载 - -执行前只读取当前任务需要的 reference 文件： - -- 需要执行阶段时，先读取 `references/phase-contracts.md`；如果当前阶段涉及接口影响分级、分档、启动规则、快速模式或完成标准，再补读 `references/operating-rules.md`。 -- 创建或更新 PRD、ADR、验收报告、词汇表、复合知识文档时，读取 `references/templates.md`。 -- archive 阶段或需要从 OpenSpec 提取产物时，读取 `references/archive-rules.md`。 - -## 内部阶段 - -9 个内部阶段，按执行顺序： - -1. clarify — 入口澄清：接收初始需求，澄清到可生成轻量 proposal。 -2. context — 上下文收集：读取 devflow 的 glossary、ADR、历史项目、compound knowledge。 -3. propose — 轻量 propose：只生成 proposal.md，不调用 openspec-propose。 -4. grill — 人类对齐澄清：evidence-driven 查证 + user-interview one-at-a-time，回写 proposal。 -5. specify — 细化 + 对齐：基于已稳定的 proposal 补全 design/specs/tasks，做 cross-artifact 对齐。 -6. audit — 架构审计：审计结果如果影响实现，回写 OpenSpec design/tasks。 -7. commit — Commit OpenSpec：检查 Draft OpenSpec 是否达到可执行状态，提交为 Committed OpenSpec。 -8. apply — OpenSpec 执行：基于 Committed OpenSpec 实现代码。 -9. archive — 回填 + 归档：从 OpenSpec 产物和 decisions.md 提炼长期档案，询问是否归档。 - -每个阶段的进入条件、动作、输出和退出标准见 `references/phase-contracts.md`。 - -关键阶段的完成判断也以 `references/phase-contracts.md` 为准；如果缺少显式 checkpoint 或能力来源声明，该阶段不得视为已完成。 - -## 快速模式 - -快速模式的具体约束见 `references/operating-rules.md`。 - -## 完成标准 - -流程完成标准见 `references/operating-rules.md`。 diff --git a/.claude/skills/sm-flow/references/archive-rules.md b/.claude/skills/sm-flow/references/archive-rules.md deleted file mode 100644 index 2d4522f..0000000 --- a/.claude/skills/sm-flow/references/archive-rules.md +++ /dev/null @@ -1,128 +0,0 @@ -# 归档规则 - -archive 阶段的目标是把 OpenSpec 产物、实现结果和过程日志转化为持久、可读、可复用的项目记忆。sm-flow 在 clarify → apply 期间只维护 `decisions.md` 作为过程日志，archive 阶段从中提取完整 devflow 档案。 - -## 目录规则 - -项目档案路径： - -```text -devflow/projects/YYYY-MM-DD-{slug}/ -``` - -archive 阶段创建以下文件： - -- `brief.md`：从 proposal.md 提取背景、目标、范围、非目标。 -- `evidence.md`：从 decisions.md 中的 evidence-driven 记录提取。 -- `decisions.md`：保持为最终版，整理格式。 -- `acceptance.md`：从实现结果和验证结果提取。 - -同时维护仓库级索引： - -- `devflow/index.md` - -按需创建以下扩展文件： - -- `prd.md` -- `research.md` -- `design.md` -- `tasks.md` -- `alignment.md` -- `adr/*.md` - -不要逐字复制完整 OpenSpec 文件，也不要重复 OpenSpec 的 proposal/design/tasks。应提炼 OpenSpec 如何指导执行：背景、证据、用户决策、任务状态、假设、验证结果、风险，以及执行中对 OpenSpec 的修正。 - -## 产物分档 - -| 分档 | 适用场景 | 必须文件 | 扩展文件 | -| --- | --- | --- | --- | -| `micro` | 小改动、低风险、需求明确 | `brief.md`、`decisions.md`、`acceptance.md` | 证据少时并入 `brief.md` | -| `standard` | 默认模式 | `brief.md`、`evidence.md`、`decisions.md`、`acceptance.md` | 按需 ADR/compound | -| `complex` | 高风险、跨模块、需求不清、多人协作 | standard 全部文件 | 按需 `prd.md`、`research.md`、`design.md`、`tasks.md`、`alignment.md` | - -## 提取映射 - -| 来源 | 提取内容 | 写入位置 | -| --- | --- | --- | -| `decisions.md`（过程日志） | question pool、evidence-driven 汇报状态、user-interview 确认状态、关键取舍 | `decisions.md`（整理格式为最终版） | -| `decisions.md`（过程日志） | evidence-driven 结论、代码/文档证据 | `evidence.md` | -| `proposal.md` | 为什么做、做什么、范围、非目标 | `brief.md` | -| `design.md` | 技术方案、关键决策、风险；只提炼长期有用内容 | `evidence.md` / 按需 `design.md` | -| `specs/**/*.md` | requirement 标题和 scenario 意图 | `brief.md` 或 `acceptance.md` 的验收追踪 | -| `tasks.md` | checkbox 状态、剩余工作、执行切片 | `acceptance.md`；复杂项目可拆 `tasks.md` | -| 测试/构建输出 | 验证命令、结果、验证类型 | `acceptance.md` | -| diagnose 记录 | 根因、修复、回归验证 | `acceptance.md` | -| 词汇表更新 | 术语和业务规则 | `devflow/glossary/CONTEXT.md` | -| 可复用经验 | 持久工程知识 | `devflow/compound/YYYY-MM-DD-{type}-{slug}.md` | -| 项目索引 | 日期、slug、领域、关键词、关联 OpenSpec、状态 | `devflow/index.md` | - -## 索引维护规则 - -`devflow/index.md` 是 context 阶段的默认入口，archive 阶段回填时必须维护。 - -最小字段： - -| 日期 | slug | 领域 | 关键词 | 关联 OpenSpec | 状态 | -| --- | --- | --- | --- | --- | --- | - -规则： - -- 每个 `devflow/projects/YYYY-MM-DD-{slug}/` 默认对应一行索引。 -- archive 阶段新建或更新项目档案时，必须新增或更新对应行。 -- 如果项目仍在进行，状态写 `active`；已验收但未 archive 写 `accepted-unarchived`；已 archive 写 `archived`；暂停写 `paused`。 -- 关键词只放能帮助 context 阶段定位的术语，不复制 brief 内容。 -- 如果无法准确判断领域或状态，写 `unknown`，并在 `acceptance.md` 记录待补。 - -## 验收记录规则 - -必须真实记录验证情况，并按类型分类： - -- **静态验证**：语法检查、grep/rg 检查、结构检查、类型检查等不运行完整功能的验证。 -- **脚本验证**：生成脚本、测试命令、构建命令、自动化检查等可重复命令。 -- **浏览器/人工验证**：需要用户或代理在界面中点击、观察、确认的行为验证。 -- **未验证**：未运行的验证必须记录原因、风险和建议补验步骤。 - -记录要求： - -- 如果验证通过，记录命令/步骤和覆盖范围。 -- 如果验证失败，记录失败摘要和是否阻塞验收。 -- 如果需要人工验证，列出明确步骤，不要用"手动测试一下"这种模糊描述。 - -## ADR 规则 - -同时满足以下条件时创建 ADR： - -1. 决策难以逆转。 -2. 缺少上下文会让未来维护者困惑。 -3. 决策来自真实权衡，而不是简单偏好。 - -项目内 ADR 存放于： - -```text -devflow/projects/YYYY-MM-DD-{slug}/adr/ -``` - -跨项目可复用决策或经验存放于： - -```text -devflow/compound/YYYY-MM-DD-decision-{slug}.md -``` - -## 归档确认 - -OpenSpec archive 是显式 human-in-the-loop 动作。archive 前必须确认 devflow 已经回填 OpenSpec 的关键执行信息： - -- archive 阶段可以建议 archive，但必须先询问用户。 -- 在用户确认前，不要执行 archive。 -- 如果用户暂不归档，在 acceptance 中记录原因或状态。 -- 如果用户确认归档，执行后记录 archive 结果和剩余档案位置。 - -## 归档交接 - -archive 阶段结束时告诉用户： - -- 创建或更新了哪些档案文件。 -- `devflow/index.md` 是否已更新。 -- 运行了哪些验证，并按静态验证、脚本验证、浏览器/人工验证、未验证分类。 -- 还剩哪些风险或后续事项。 -- 明确询问：是否现在 archive OpenSpec change？ diff --git a/.claude/skills/sm-flow/references/operating-rules.md b/.claude/skills/sm-flow/references/operating-rules.md deleted file mode 100644 index 3cc5d34..0000000 --- a/.claude/skills/sm-flow/references/operating-rules.md +++ /dev/null @@ -1,111 +0,0 @@ -# 运行规则 - -本文件承载稳定但不必放在顶层 `SKILL.md` 的运行规则。 - -## 接口影响分级 - -接口影响分级判断的是"记录在哪里、是否需要独立文档"，不是判断"是否需要关注"。凡涉及字段、DTO、service 方法、API、事件、回调、数据库契约、命令契约、跨模块调用语义或内部决策逻辑变化，都必须先做分级。 - -| 级别 | 判断条件 | 产物要求 | -| --- | --- | --- | -| L1 内部实现 | 不改变任何调用方可观察的接口、字段、状态、错误码、数据范围、排序、过滤、权限结果、状态流转、副作用或文档承诺 | 不需要接口影响文档，只在 OpenSpec tasks 或 acceptance 记录验证 | -| L2 内部接口 | 改 DTO、service 方法、内部事件、内部 RPC 或内部判断逻辑，且所有消费者都在同一实现范围内 | 必须记录接口影响范围，可内联到 OpenSpec design/specs/tasks 或 devflow evidence/decisions | -| L3 协作接口 | 影响其他模块、其他服务、前端、外部系统、跨团队消费者、数据库契约、消息事件、回调或 SDK | 必须产出独立接口文档或等价独立章节 | -| L4 破坏性接口 | 删除字段、改字段语义、改状态机、改错误码、破坏兼容、旧调用方可能失败，或需要迁移、灰度、回滚 | 独立接口文档 + 迁移/回滚说明；必要时创建 ADR | - -判断策略： - -- 如果只是修复 bug，让接口回到原 OpenSpec 或原文档承诺，通常是 L1/L2。 -- 如果判断逻辑改变了返回数据、错误码、状态、权限结果、排序/过滤、幂等性、时序或副作用，至少按 L3 检查。 -- 如果旧调用方不改代码会失败、少数据、多数据、状态不同或错误码不同，按 L4 处理。 -- 如果无法确定调用方边界或兼容性，默认提高一级并作为 `user-interview` 问题等待确认。 - -## 启动检查 - -1. 识别用户命令意图： - - `/sm-flow`（无参数）：完整流程，从 clarify 开始。 - - `/sm-flow apply [change]`：只执行，检查 commit gate → apply。 - - `/sm-flow explore`：带上下文的探索模式，不走标准阶段链。 - - `/sm-flow archive [change]`：收尾，回填 devflow + 归档确认。 - - 自然语言指定阶段继续：识别意图后，自动补做最小前置检查，然后从指定阶段继续。 -2. 判断启动模式： - - 完整模式：用户提供粗略想法或初始 PRD。 - - Research 模式：用户已有 research，需要转成或修正 OpenSpec。 - - PRD 文件模式：用户提供已有 PRD 路径。 - - 恢复模式：用户希望从某个阶段继续（补做最小前置检查）。 - - 快速模式：小改动，合并 gate（见下文）。 -3. 如果缺少 `devflow/`，初始化： - - `devflow/projects/` - - `devflow/glossary/CONTEXT.md` - - `devflow/compound/` -4. 如果根目录存在旧 `CONTEXT.md`，且 `devflow/glossary/CONTEXT.md` 不存在或为空，询问用户是迁移还是合并。 -5. 检查 OpenSpec 和子 skill 是否可用： - - OpenSpec 能力：`openspec-propose`、`openspec-apply-change`、`openspec-archive-change`。 - - 辅助能力：`to-prd`、`grill-with-docs`、`diagnose`、`tdd`、`zoom-out`。 -6. 如果 OpenSpec 不可用，不要直接绕过；使用内置执行协议（见 `references/fallbacks.md`），并在 apply 前向用户说明。 - -## 项目标识规则 - -- 整个流程使用同一个 slug。 -- 优先使用 OpenSpec change name。 -- 如果还没有，则从功能标题生成 kebab-case slug。 -- 项目档案目录格式：`devflow/projects/YYYY-MM-DD-{slug}/`。 -- 如果目录已存在，默认恢复该项目；除非用户明确要求新开一轮。 - -## Devflow 产物分层 - -Devflow 是 sm-flow 自动维护的项目长期记忆层，不复制 OpenSpec 的执行产物。 - -**过程日志**（clarify → apply 期间维护）： - -- `decisions.md`：question pool、evidence-driven 汇报状态、user-interview 确认状态、关键取舍、风险接受、OpenSpec 回写记录、冲突分类记录。 - -**最终档案**（archive 阶段从 decisions.md + OpenSpec 产物提取）： - -- `brief.md`：背景、目标、范围、非目标、分档、关联 OpenSpec change。 -- `evidence.md`：代码/文档证据、历史决策、evidence-driven 结论和汇报状态。 -- `acceptance.md`：实现结果、验证命令、未验证项、归档状态、后续事项。 - -**按需产物**（archive 阶段按需创建）： - -- `prd.md`：需求复杂、用户明确要求、或需要对外协作。 -- `research.md`：存在真实调研、代码考古、竞品/API 对比或复杂方案比较。 -- `design.md`：不适合放进 OpenSpec design 的长期背景或架构审计摘要。 -- `tasks.md`：跨会话的人类追踪；执行任务仍属于 OpenSpec。 -- `alignment.md` / `clarifications.md`：仅在 gap 或澄清很多时使用。 -- `adr/*.md` 和 `compound/*.md`：仅在满足 ADR / compound knowledge 规则时使用。 - -**规模分档**： - -- `micro`：小且低风险，gate 合并（见快速模式），最终档案同 standard。 -- `standard`：默认模式。 -- `complex`：高风险、跨模块、需求不清或多人协作时，在 standard 基础上按需增加扩展产物。 - -## 快速模式 - -快速模式适用于小而低风险的变更。它合并 gate 而不仅仅是压缩产物： - -``` -standard 流程：clarify → context → propose checkpoint → grill → specify → audit checkpoint → commit -micro 流程：clarify+context 合并 checkpoint → propose+specify 合并 checkpoint → grill（最少 1 个问题） → commit（简化检查） -``` - -micro 的定位：**gate 变少但保留最关键的**（grill 最小澄清 + commit gate）。 - -无论什么模式，以下内容必须保留： - -- context 最小上下文收集：至少检查 glossary 和相关 ADR。 -- grill 最小澄清：至少一个术语问题、一个边界问题、一个验收问题；evidence-driven 结论仍需汇报。 -- commit gate：确认没有未解决用户问题、接口影响已记录、OpenSpec tasks/specs 可执行。 -- apply 仍由 OpenSpec tasks/specs 驱动执行。 -- archive 轻量回填：记录验收结果、OpenSpec 链接和归档状态。 - -## 完成标准 - -只有同时满足以下条件，流程才算完成： - -- OpenSpec proposal/design/specs/tasks 已生成或更新到可执行状态。 -- 实现或规划工作已完成，且执行依据来自 OpenSpec。 -- 已运行验证，或已记录未运行验证的原因。 -- `devflow/projects/YYYY-MM-DD-{slug}/` 包含 brief.md、evidence.md、decisions.md、acceptance.md。 -- 用户知道剩余风险与下一步，并已被询问是否归档 OpenSpec change。 diff --git a/.claude/skills/sm-flow/references/phase-contracts.md b/.claude/skills/sm-flow/references/phase-contracts.md deleted file mode 100644 index 77a667e..0000000 --- a/.claude/skills/sm-flow/references/phase-contracts.md +++ /dev/null @@ -1,280 +0,0 @@ -# 阶段契约 - -本文件是 SM Flow 的逐阶段执行准则。核心原则：**sm-flow 编排 OpenSpec，OpenSpec 指挥执行，执行结果回填 devflow**。 - -执行顺序：clarify → context → propose → grill → specify → audit → commit → apply → archive。 - -## clarify — 入口澄清 - -**进入条件**：用户提供粗略想法、初始 PRD、已有 research、issue，或要求启动 SM Flow。 - -**动作**： -- 收集问题、期望结果、目标用户、涉及代码区域、约束条件和可能的非目标。 -- 如果用户已有 research，先识别它是否已经包含用户价值、技术方案、验收标准和任务拆分。 -- 如果输入过于模糊，最多追加三轮聚焦问题。 -- 当答案会改变 OpenSpec proposal/specs/tasks 时，优先一次只问一个问题。 -- 如果需要判断 `micro / standard / complex` 分档，补读 `references/operating-rules.md`。 - -**退出条件**： -- 问题可以用 1-2 句话说清楚。 -- 期望结果可以用 1-2 句话说清楚。 -- 已列出已知影响代码或模块；如果未知，也明确标记。 -- 可以生成 OpenSpec change slug。 - -**输出**： -- 入口摘要。 -- 初步 slug。 -- devflow 规模分档：`micro` / `standard` / `complex`。 - -## context — 上下文收集 - -**进入条件**：clarify 已经有足够信息定位领域、项目或变更方向。 - -**动作**： -- 优先读取 `devflow/index.md`，按日期、slug、领域、关键词和关联 OpenSpec 定位候选项目。 -- 如果 `devflow/index.md` 不存在，先从 `devflow/projects/` 现有目录初始化轻量索引，再继续本次上下文收集。 -- 读取 `devflow/glossary/CONTEXT.md`，提取相关术语和业务规则。 -- 搜索 `devflow/projects/` 中相关 PRD、design、tasks、acceptance 和 ADR。 -- 搜索 `devflow/compound/` 中可复用 learning、trick、decision、explore。 -- 记录哪些上下文会影响 OpenSpec proposal/design/specs/tasks。 -- 如果发现旧根目录 `CONTEXT.md` 与 `devflow/glossary/CONTEXT.md` 冲突，暂停并向用户汇报。 - -**退出条件**： -- 已形成"OpenSpec 输入上下文摘要"。 -- 已记录 `devflow/index.md` 的使用状态：已命中 / 已初始化 / 无相关条目。 -- 已列出相关 ADR 和不能违反的历史决策。 -- 已列出需要写入或修正 OpenSpec 的上下文点。 - -**输出**： -- 上下文摘要，写入 `decisions.md`（过程日志）。会影响实现的上下文必须标记为"需进入 OpenSpec"。 - -## propose — 轻量 propose - -**进入条件**：clarify + context 已经足够生成轻量 proposal。 - -**执行者**：sm-flow 内置协议。**不调用 openspec-propose**（完整 OpenSpec 产物留待 specify 阶段生成）。 - -**动作**： -- 创建或识别 `openspec/changes/{slug}/`。 -- 写入 `proposal.md`，包含：问题、建议方案、范围、非目标、来自 devflow 的上下文约束、风险。 -- **不生成 design.md、specs/、tasks.md**——这些留待 grill 澄清需求后在 specify 阶段补全。 -- 用 context 阶段的 devflow 上下文增强 proposal。 -- 在承诺方案方向前，先检查相关仓库代码。 - -**退出条件**： -- `openspec/changes/{slug}/proposal.md` 存在。 -- 关键假设已显式记录。 - -**输出**： -- Draft OpenSpec proposal.md（轻量版）。 - -**Human checkpoint**： -- 向用户简要说明 proposal 范围、关键假设、主要风险、devflow 上下文如何影响方案。 -- 询问是否继续进入 grill 澄清阶段；用户明确要求"全自动执行"时可跳过等待。 - -## grill — 人类对齐澄清 - -**进入条件**：propose 已有轻量 proposal.md。 - -**显式子 skill**：`grill-with-docs`。进入本阶段必须调用 `.agents/skills/grill-with-docs/SKILL.md`。 - -**动作**： -- 优先使用 `grill-with-docs`。 -- 进入 grill 时先建立一个 question pool，并记录到 `decisions.md`： - - 默认至少覆盖术语、边界、验收三个维度。 - - 如果变更涉及多模块、接口、权限、下游消费者、响应结构或生命周期规则，先把这些维度补进问题池。 -- 逐项标记每个问题的模式： - - `evidence-driven`：问题能通过代码、文档、测试、OpenSpec 或既有 ADR 证明；代理先查证，再向用户汇报证据、结论和是否需要确认。 - - `user-interview`：问题涉及产品偏好、范围边界、验收口径、风险接受度或价值取舍；必须问用户并等待确认。 -- evidence-driven 和 user-interview 的推进节奏：先批量查证 evidence-driven 并一次性汇报结论，再逐个处理 user-interview 问题。不要把所有问题攒到最后一起问。 -- 一次只问一个 `user-interview` 问题。 -- 每个 `user-interview` 问题必须等待用户显式回答，并在 decisions.md 中记录：问题原文、用户原话、确认状态（已确认/未确认）。未确认的问题不能从 question pool 移除。 -- 单个 `user-interview` 的确认只能解除该问题本身的阻塞，不能被解释为进入 apply 或修改执行目标文件的授权。 -- 对接口影响等级、消费者边界或兼容性存在不确定时，必须作为 `user-interview` 问题等待用户确认。 -- 如果澄清结果影响实现，必须回写 proposal.md。 -- 术语一旦确认，更新 `devflow/glossary/CONTEXT.md`。 -- 对难以逆转、依赖上下文、源自真实权衡的决策创建 ADR。 - -**退出条件**： -- question pool 已建立并覆盖当前 change 所需维度。 -- 至少解决三个高价值澄清或验证问题，并记录每个问题属于 `evidence-driven` 还是 `user-interview`。 -- 所有 evidence-driven 结论已向用户汇报。 -- 所有 user-interview 决策已获得用户确认。 -- 没有未解决或代理代确认的 user-interview 问题。 -- 没有未判级或未确认的接口影响问题。 -- 影响实现的结论已回写 proposal.md。 -- 单个 grill 决策确认不等于 apply 授权；grill 完成后必须停在 commit，等待用户明确要求进入 apply。 -- question pool、evidence-driven 结论、user-interview 确认必须写入 `decisions.md` 文件，不能只记录在对话中。 - -**输出**： -- 更新后的 proposal.md。 -- 澄清记录：写入 `decisions.md`。包含 question pool、evidence-driven 汇报状态、user-interview 确认状态。 -- 更新后的词汇表和 ADR。 - -**Human checkpoint**： -- 汇报已解决和未解决的问题、proposal 变更、术语和 ADR 更新。 -- 询问是否继续进入 specify 细化阶段。 - -## specify — 细化 + 对齐 - -**进入条件**：grill 已退出，需求已通过澄清稳定下来。 - -**显式子 skill**：`openspec-propose`（基于已稳定的 proposal 补全完整 OpenSpec）；`to-prd`（按需生成 PRD）。进入本阶段必须先声明调用方式。 - -**动作**： -- 基于已稳定的 proposal.md 补全 design.md、specs/、tasks.md： - - 优先调用 `openspec-propose`，输入中明确说明"proposal.md 已存在，本次只需补全 design/specs/tasks"。 - - 如果不可用，执行 `references/fallbacks.md#openspec-提案-降级`。 -- 如果没有结构化 PRD，按需按 `to-prd` 协议生成 `brief.md`；复杂需求、对外协作或用户明确要求时再生成 `prd.md`。 -- `micro` 模式默认不创建独立 PRD，除非用户要求或需求复杂度升级。 -- 用 grill 阶段的 decisions.md 记录增强 OpenSpec 产物：确保 design/specs/tasks 反映所有已确认的决策。 -- **显式 cross-artifact 对齐检查**——在 checkpoint 中输出对齐检查表： - - `brief/prd` 中的目标、范围、非目标和验收预期 → `proposal` 是否覆盖。 - - `proposal` 中的范围、约束和关键承诺 → `design` 是否覆盖。 - - `design` 中影响实现的约束、接口影响和架构结论 → `specs` 或 `tasks` 是否覆盖。 - - `specs` 中的可观察行为 → `tasks` 是否覆盖为可执行切片。 - - 每项标记：已对齐 / 存在 gap。 -- 检查是否涉及接口影响： - - 接口影响分级定义见 `references/operating-rules.md#接口影响分级`。 - - 是否改变字段、DTO、service 方法、API、事件、回调、数据库契约、命令契约或跨模块调用语义。 - - 接口内部判断逻辑是否改变调用方可观察行为。 - - 按 L1/L2/L3/L4 记录接口影响等级；不确定时标记为 `user-interview` 问题。 -- 如果存在 gap，在进入下一阶段前修复 OpenSpec。 -- 如果发现不一致，优先修正 OpenSpec，而不是只修改 devflow 文档。 - -**退出条件**： -- `design.md`、`specs/`、`tasks.md` 存在且与 proposal 对齐。 -- `brief.md` 已覆盖背景、目标、范围和非目标；复杂需求存在独立 `prd.md` 或用户明确不需要 PRD。 -- cross-artifact 对齐检查表已生成（4 行，每行标记已对齐/存在 gap），没有未处理 gap。 -- 涉及接口变更时，已记录接口影响等级和产物要求；不确定项已标记。 -- 所有已知冲突已修正或等待用户决策。 - -**输出**： -- 完整的 Draft OpenSpec：proposal.md + design.md + specs/ + tasks.md。 -- `brief.md`，以及按需创建的 `prd.md`。 -- cross-artifact 对齐检查表（写入 checkpoint 或 decisions.md）。 -- 必要的 OpenSpec 修正。 - -## audit — 架构审计 - -**进入条件**：specify 已退出，完整 OpenSpec 产物已存在。 - -**显式子 skill**：`zoom-out`。进入本阶段必须调用 `.agents/skills/zoom-out/SKILL.md`。 - -**动作**： -- 画出输入 → 处理 → 输出的模块链路。 -- 识别跨模块依赖、数据所有权、生命周期和耦合风险。 -- 检查是否与既有架构、ADR、OpenSpec design 冲突。 -- 用不超过五句话写出架构风险评估。 -- 如果审计结果影响实现，必须回写 OpenSpec design/tasks；只写入 devflow design 不够。 -- 审计结论写入 `decisions.md`。 - -**退出条件**： -- 架构风险已被接受，或流程返回 grill/specify 修正 OpenSpec。 -- OpenSpec design/tasks 已反映会影响实现的架构审计结论。 - -**输出**： -- 架构审计记录，写入 `decisions.md`；复杂架构审计可拆出 `design.md`。 -- 必要的 OpenSpec design/tasks 修正。 - -**Human checkpoint**： -- 用不超过五句话向用户说明架构风险、OpenSpec 修正点和实现计划。 -- 询问是否进入 commit。 - -## commit — Commit OpenSpec - -**进入条件**： -- grill 已解决术语、边界、验收三个维度的高价值问题。 -- 所有 `user-interview` 问题都已获得用户显式确认。 -- audit 已经完成，或快速模式下已记录跳过原因；快速模式定义见 `references/operating-rules.md#快速模式`。 -- Draft OpenSpec 已回写所有会影响实现的澄清、接口影响和架构审计结论。 - -**动作**： -- 检查 proposal 是否说明为什么做、做什么、范围和非目标。 -- 检查 design 是否记录上下文约束、关键技术决策、架构风险和接口影响。 -- 检查 specs 是否表达外部可观察行为，并覆盖验收口径。 -- 检查 tasks 是否是可执行的纵向切片，而不是泛泛描述。 -- 复核 cross-artifact 对齐：`brief/prd → proposal → design → specs → tasks` 是否闭环，没有把字段、范围项、验收行为或实现切片丢在上游产物里。 -- 检查 `decisions.md` 中所有影响实现的发现，是否已回写到 proposal、design、specs 或 tasks。 -- 接口影响分级定义见 `references/operating-rules.md#接口影响分级`。 -- 检查接口影响是否已按 L1/L4 判级；L3/L4 是否有独立接口文档或等价独立章节。 -- 检查没有未汇报的 evidence-driven 结论，没有未确认的 user-interview 问题，没有 devflow/OpenSpec 冲突。 -- 如果检查失败，返回 propose、grill、specify 或 audit 修正 Draft OpenSpec。 - -**退出条件**： -- Draft OpenSpec 已达到可执行状态，并记录为 Committed OpenSpec。 -- apply 所需的 proposal、design、specs 和 tasks 均存在且一致；commit checkpoint 必须验证文件实际存在于磁盘，如果任一文件不存在，commit 失败，返回 specify 补写。 -- 所有 preflight 风险已消除或明确记录为已接受。 - -**输出**： -- Committed OpenSpec 状态说明。 -- preflight 检查结果，写入 `decisions.md` 或 `acceptance.md`。 - -**Human checkpoint**： -- 用不超过五句话说明 Committed OpenSpec 的范围、接口影响、剩余风险和执行计划。 -- 询问是否进入 apply；除非用户在启动时明确要求"全自动执行"，必须等待用户明确说出进入 apply、开始实现、执行修改或等价授权。 -- 不得把 grill 的单个决策确认当作本 checkpoint 的授权。 - -## apply — OpenSpec 执行 - -**进入条件**： -- `openspec/changes/{slug}/` 中 proposal/design/specs/tasks 已通过 commit，成为 Committed OpenSpec。 -- commit 后已获得用户明确的 apply 授权，除非用户在启动时要求"全自动执行"。 -- devflow 与 OpenSpec 没有未解决冲突。 -- 没有未解决的 user-interview 问题、未判级接口影响、未汇报 evidence-driven 结论或未接受架构风险。 - -**显式子 skill**：`openspec-apply-change`；遇到 bug/不确定行为时显式调用 `diagnose`；需要测试驱动时显式调用 `tdd`。进入本阶段必须调用指定子 skill，不得静默跳过。 - -**动作**： -- 优先调用 `openspec-apply-change`。 -- 执行依据是 OpenSpec specs/tasks；devflow 只能作为上下文参考。 -- 按 OpenSpec tasks 的纵向切片实现。 -- 进入实现前先汇报本阶段的 capability 来源、当前 task 进度和本轮要推进的切片；否则 apply 不算真正开始。 -- 当用户质疑、用户要求修改、代码检查、测试失败或运行行为与 OpenSpec 冲突时，做三类判断： - - OpenSpec 不准（规格遗漏、边界未覆盖、验收口径缺失）→ 暂停 apply，修正 OpenSpec 后重新提交。 - - 代码偏离（实现没按 OpenSpec 做）→ 修正代码，不改 OpenSpec。 - - 不确定根因、涉及设计方向、用户改变目标或范围 → 暂停并等待用户确认。 -- 判断结果、证据、用户确认和 OpenSpec 回写状态必须记录到 `decisions.md`。 -- 当用户要求、行为复杂或回归风险高时使用 TDD。 -- 当测试失败、行为意外或原因不确定时使用 diagnose。 -- 如果 diagnose 发现根因是 OpenSpec 不准确，先修正 OpenSpec，再继续 apply。 -- 修改文件前遵守仓库指令，例如 `AGENTS.md`。 - -**退出条件**： -- OpenSpec tasks 已完成，或剩余 tasks 已明确记录。 -- 所有实现期冲突已分类并处理；没有未确认的规格遗漏、设计冲突或用户变更。 -- 已运行验证，或记录了未验证原因。 -- 已列出已知限制。 - -**输出**： -- 代码变更、必要测试和实现说明。 -- 更新后的 OpenSpec task 状态。 -- 冲突记录写入 `decisions.md`。 - -## archive — 回填 + 归档 - -**进入条件**：实现或规划工作已经达到可交接状态。 - -**显式子 skill**：`openspec-archive-change` 在用户确认 archive 后调用；archive 回填由 `sm-flow` 执行。必须调用子 skill，不得静默跳过。 - -**动作**： -- 遵循 `references/archive-rules.md`。 -- 从 `decisions.md`（过程日志）+ OpenSpec 产物提炼完整 devflow 档案： - - `brief.md`：从 proposal.md 提取背景、目标、范围、非目标。 - - `evidence.md`：从 decisions.md 中的 evidence-driven 记录提取。 - - `decisions.md`：保持为最终版，整理格式。 - - `acceptance.md`：从实现结果和验证结果提取。 -- 只在复杂场景按需拆出 PRD/research/design/tasks/alignment。 -- 写入或更新验收记录，并区分静态验证、脚本验证、浏览器/人工验证、未验证。 -- 如果本次流程产生可复用经验，写入 compound knowledge。 -- 更新 `devflow/index.md`，记录日期、slug、领域、关键词、关联 OpenSpec 和状态。 -- 询问用户是否要 archive OpenSpec change；不要默认执行归档。 - -**退出条件**： -- `devflow/projects/YYYY-MM-DD-{slug}/` 包含 brief.md、evidence.md、decisions.md、acceptance.md；archive checkpoint 必须列出所有已创建的文件路径，验证文件实际存在于磁盘。 -- `devflow/index.md` 已包含或更新本项目条目。 -- 用户已被询问是否 archive OpenSpec change。 - -**输出**： -- 完整 devflow 档案。 -- 归档交接清单：创建或更新了哪些文件、验证分类、剩余风险、是否 archive。 diff --git a/.claude/skills/sm-flow/references/templates.md b/.claude/skills/sm-flow/references/templates.md deleted file mode 100644 index b428144..0000000 --- a/.claude/skills/sm-flow/references/templates.md +++ /dev/null @@ -1,386 +0,0 @@ -# 模板 - -这些是最小模板。只有在能提升未来可读性时，才增加额外章节。保留 PRD、ADR、OpenSpec、slug 等行业术语，其余说明尽量使用中文。 - -## Brief 模板 - -```markdown -# {标题} Brief - -## 背景 - -- 用户目标：{goal} -- 当前问题：{problem} -- 关联 OpenSpec：`openspec/changes/{slug}/` -- devflow 分档：micro | standard | complex - -## 范围 - -- 本次要做：{in scope} -- 本次不做：{out of scope} -- 影响区域：{modules/files if known} - -## OpenSpec 对齐 - -- proposal 覆盖状态：已覆盖 / 待修正 / 不适用 -- specs 覆盖状态：已覆盖 / 待修正 / 不适用 -- tasks 覆盖状态：已覆盖 / 待修正 / 不适用 -``` - -## Evidence 模板 - -```markdown -# {标题} Evidence - -## 证据 - -| 来源 | 证据 | 结论 | 是否已汇报 | -| --- | --- | --- | --- | -| {file/doc/test/ADR} | {evidence summary} | {conclusion} | 是 / 否 | - -## Evidence-driven 结论 - -- 结论：{conclusion} - - 证据：{evidence} - - 风险：{risk if any} - - 用户确认：需要 / 不需要 / 已确认 -``` - -## Decisions 模板 - -```markdown -# {标题} Decisions - -## Question Pool - -| # | 维度 | 问题 | 模式 | 状态 | -|---|---|---|---|---| -| Q1 | 术语 | {question} | evidence-driven / user-interview | 已解决 / 未解决 | -| Q2 | 边界 | {question} | evidence-driven / user-interview | 已解决 / 未解决 | -| Q3 | 验收 | {question} | evidence-driven / user-interview | 已解决 / 未解决 | - -## Evidence-driven - -| 结论 | 证据来源 | 是否已汇报用户 | -|---|---|---| -| {conclusion} | {file/doc/test/ADR} | 已汇报 / 待汇报 | - -## User-interview - -| 问题原文 | 用户原话 | 确认状态 | OpenSpec 回写 | -|---|---|---|---| -| {question} | {user's exact words} | 已确认 / 未确认 | 已回写 / 不影响 / 待回写 | - -## 关键取舍 - -- 决策：{decision} - - 原因：{why} - - 影响：{impact} - - 风险接受：{accepted by whom/when} -``` - -## 接口影响记录模板 - -```markdown -# {标题} 接口影响记录 - -## 分级 - -- 级别：L1 内部实现 / L2 内部接口 / L3 协作接口 / L4 破坏性接口 -- 判级原因：{why this level} -- 是否需要独立接口文档：是 / 否 - -## 变更对象 - -- 接口/字段/DTO/事件/回调/数据库契约： -- 判断逻辑变化： -- 可观察行为变化：返回数据 / 状态 / 错误码 / 权限结果 / 过滤排序 / 幂等性 / 时序 / 副作用 / 无 - -## 影响范围 - -- 调用方/消费者： -- 是否跨模块/跨服务/跨团队： -- 旧调用方是否需要改动： - -## 兼容与迁移 - -- 是否向后兼容： -- 迁移/灰度/回滚要求： -- 风险接受： - -## 验收方式 - -- 如何证明新行为正确： -- 如何证明旧行为未破坏： -- 需要用户确认的问题： -``` - -## 实现期冲突记录模板 - -```markdown -# {标题} 实现期冲突记录 - -## 冲突摘要 - -- 触发来源：用户质疑 / 用户变更 / 代码发现 / 测试失败 / 运行行为 -- 冲突对象：proposal / design / specs / tasks / ADR / 代码行为 -- 分类：实现偏差 / 规格遗漏 / 设计冲突 / 用户变更 - -## 证据 - -- OpenSpec 依据： -- 代码或测试证据： -- 用户反馈： - -## 处理 - -- 决策： -- 是否需要用户确认：是 / 否 -- OpenSpec 回写：不需要 / 已回写 / 待回写 -- 代码处理： -- 验证方式： -``` - -## PRD 模板 - -```markdown -# {标题} PRD - -## 问题陈述 - -用用户视角描述问题。 - -## 解决方案 - -用用户视角描述预期解决方案。 - -## 用户故事 - -1. 作为{角色}，我希望{能力}，以便{收益}。 - -## 实现决策 - -- 决策：{decision} - - 原因：{why} - - 影响：{affected modules or behavior} - -## 测试决策 - -- 好测试应该通过{public interface}验证{observable behavior}。 -- 必须覆盖：{critical paths} -- 不测试：{explicit exclusions} - -## 非目标 - -- {excluded behavior} - -## 补充说明 - -- {open question or useful context} -``` - -## 词汇表模板 - -```markdown -# 上下文词汇表 - -## 术语 - -### {术语} - -- 定义：{precise definition} -- 使用场景：{feature/module/context} -- 备注：{ambiguities, synonyms, or rejected meanings} - -## 业务规则 - -- {rule}: {meaning and source} -``` - -## ADR 模板 - -```markdown -# ADR-{编号}: {决策标题} - -**状态**：提议中 | 已接受 | 已废弃 -**日期**：YYYY-MM-DD - -## 背景 - -是什么情况迫使我们做这个决策？ - -## 决策 - -我们选择了什么？ - -## 替代方案 - -| 方案 | 拒绝原因 | -| --- | --- | -| {option} | {reason} | - -## 后果 - -### 正面 - -- {benefit} - -### 负面 - -- {cost or risk} -``` - -## 技术调研模板 - -```markdown -# {标题} 技术调研 - -## 摘要 - -- 变更原因：{reason} -- 变更范围：{scope} -- 主要技术方案：{approach} - -## 源产物 - -- OpenSpec change: `openspec/changes/{slug}/` -- 关联 PRD: `prd.md` 或 `brief.md` - -## 关键发现 - -- {finding} - -## 假设 - -- {assumption and validation status} -``` - -## 设计模板 - -```markdown -# {标题} 设计 - -## 架构摘要 - -描述输入 → 处理 → 输出。 - -## 关键决策 - -- {decision}: {reason} - -## 模块地图 - -| 模块 | 职责 | 备注 | -| --- | --- | --- | -| {module} | {responsibility} | {notes} | - -## 架构审计 - -- 风险：{risk} -- 缓解：{mitigation} -``` - -## 任务模板 - -```markdown -# {标题} 任务 - -## 需求追踪 - -| 需求 | 状态 | 备注 | -| --- | --- | --- | -| {requirement} | 已完成 / 待处理 / 部分完成 | {notes} | - -## 实现任务 - -- [ ] {task} -``` - -## 验收模板 - -```markdown -# {标题} 验收 - -## 结果 - -已接受 / 部分接受 / 未接受。 - -## 验证 - -### 静态验证 - -- 命令/检查：`{command or check}` -- 结果：{passed/failed/not run} -- 备注：{important output or reason not run} - -### 脚本验证 - -- 命令：`{command}` -- 结果：{passed/failed/not run} -- 备注：{important output or reason not run} - -### 浏览器/人工验证 - -- 步骤：{manual steps} -- 结果：{passed/failed/not run} -- 备注：{observations or reason not run} - -## 已完成范围 - -- {completed behavior} - -## 已知限制 - -- {limitation} - -## Bug 修复和诊断 - -- {bug}: {diagnosis summary and regression coverage} - -## 交接 - -- 下一步：{archive, deploy, review, or follow-up} -- OpenSpec 归档确认：{已询问/用户确认归档/用户暂不归档/不适用} -``` - -## Cross-Artifact 对齐检查表模板 - -specify 阶段的 checkpoint 必须包含此检查表。每项标记"已对齐"或"存在 gap"。 - -```markdown -## Cross-Artifact 对齐检查 - -| 上游 → 下游 | 检查内容 | 状态 | -|---|---|---| -| brief/prd → proposal | 目标、范围、非目标、验收预期是否进入 proposal | 已对齐 / 存在 gap | -| proposal → design | 范围、约束、关键承诺是否进入 design | 已对齐 / 存在 gap | -| design → specs/tasks | 影响实现的约束、接口影响、架构结论是否进入 specs 或 tasks | 已对齐 / 存在 gap | -| specs → tasks | 可观察行为是否被 tasks 覆盖为可执行切片 | 已对齐 / 存在 gap | - -### Gap 详情（如有） - -- gap 1：{描述哪个字段/约束/行为/切片只停留在上游，未进入下游} - - 修复：{如何修正 OpenSpec} -``` - -## 复合知识模板 - -```markdown -# {标题} - -**类型**：learning | trick | decision | explore -**日期**：YYYY-MM-DD - -## 背景 - -这条经验来自哪里？ - -## 经验 - -未来代理应该复用什么经验？ - -## 适用性 - -什么时候适用？什么时候不适用？ -``` - diff --git a/AGENTS.md b/AGENTS.md index a831ef7..ee7580c 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,43 +1,107 @@ - -# GitNexus — Code Intelligence +# CLAUDE.md + +## Defaults + +- Reply in **Chinese** unless I explicitly ask for English. +- No emojis. +- Do not truncate important outputs (logs, diffs, stack traces, commands, or critical reasoning that affects + safety/correctness). + +## Refactor policy (legacy code) + +- When existing code is a "big ball of mud" (hard to maintain, clearly bad design, + full of hacks), prefer a **clean, full refactor** over stacking more patches + on top of it. +- A refactor may completely replace internal structure + (functions, modules, classes, data flow). +- By default, try to preserve externally observable behaviour. + If you intentionally change behaviour or protocols, you MUST: + - Call out clearly that this is a **behaviour/protocol change**. + - Explain why the change is necessary and which code paths/consumers are affected. + - Update or add tests to cover the new behaviour. + +## Before touching code (mandatory) + +Find reuse opportunities + Trace the call/dependency chain and impact radius: + +- Use semantic code search first via `codebase-retrieval` tool. +- Confirm understanding with LSP: `goToDefinition`, `findReferences`. +- Use Grep/Glob for verifying and understanding additional code snippets. + +## Red lines + +- No copy-paste duplication. +- Do not break existing externally observable behaviour **unless**: + - It is part of a deliberate refactor as described in the refactor policy, and + - You clearly document the behavioural change and its impact. +- Do not proceed with a known-wrong approach. +- Critical paths must have explicit error handling. +- Never implement "blindly": always confirm understanding via code reading + references. + +## Task sizing + +- **Simple** +- Criteria — single file, clear requirement, < 20 lines changed, + clearly local impact. +- Handling — after doing the "Before touching code" steps + (research + impact analysis + internal three-question checklist), + you may execute directly with minimal explanation. +- A very short context line is enough; + a full breakdown of the checklist is not required. + +- **Medium** + - Criteria — 2–5 files, or requires some research, or impact is not obviously local. + - Handling — write a short plan (bullet points) → then implement. + - Briefly surface the checklist result in the reply + (1–3 short lines describing real issue, key reuse, and main impact). + +- **Complex** + - Criteria — architecture changes, multiple modules, high uncertainty or risk. + - Handling — follow this workflow: + 1. **RESEARCH**: inspect code and facts only (no proposals yet). + 2. **PLAN**: present options + tradeoffs + recommendation; + use `AskUserQuestion` actively to align with the user; + wait for user's confirmation. + 3. **EXECUTE**: implement exactly the approved plan. + 4. **REVIEW**: self-check (tests, edge cases, cleanup). + +## Git + +- Do not commit unless I explicitly ask. +- Do not push unless I explicitly ask. +- Before writing a commit message, glance at a few recent commits and match the repo's style: + - `git log -n 5 --oneline` +- If there is no obvious existing style, use this default format: + - `(): ` +- Before any commit: run `git diff` and confirm the exact scope of changes. +- Never force-push to `main` / `master` unless the user approves. +- Do not add attribution lines in commit messages. + +## Security + +- Never hardcode secrets (keys/passwords/tokens). +- Never commit `.env` files or any credentials. +- Validate user input at trust boundaries (APIs, CLIs, external data sources). + +## Quality & cleanup + +- Prefer clarity and simplicity first (KISS); apply DRY to remove obvious + copy-paste duplication when it does not hurt readability. +- If you change a function signature, update **all** call sites. +- After changes: + - Remove temporary files. + - Remove dead/commented-out code. + - Remove unused imports. + - Remove debug logging that is no longer needed. +- Run the smallest meaningful verification (lint/test/build) for the parts you touched. + +## Windows / PowerShell (if used) + +- PowerShell does not support `&&`; use `;` to chain commands. +- Quote paths that contain spaces or non-ASCII characters. + +## Baisc Infos + +Unless directly relevant to the user's current question, you should avoid proactively mentioning, illustrating, or +trailing off into the following information in 99% of cases: -This project is indexed by GitNexus as **SuperBizAgent-java** (1528 symbols, 2828 relationships, 87 execution flows). Use the GitNexus MCP tools to understand code, assess impact, and navigate safely. - -> If any GitNexus tool warns the index is stale, run `npx gitnexus analyze` in terminal first. - -## Always Do - -- **MUST run impact analysis before editing any symbol.** Before modifying a function, class, or method, run `gitnexus_impact({target: "symbolName", direction: "upstream"})` and report the blast radius (direct callers, affected processes, risk level) to the user. -- **MUST run `gitnexus_detect_changes()` before committing** to verify your changes only affect expected symbols and execution flows. -- **MUST warn the user** if impact analysis returns HIGH or CRITICAL risk before proceeding with edits. -- When exploring unfamiliar code, use `gitnexus_query({query: "concept"})` to find execution flows instead of grepping. It returns process-grouped results ranked by relevance. -- When you need full context on a specific symbol — callers, callees, which execution flows it participates in — use `gitnexus_context({name: "symbolName"})`. - -## Never Do - -- NEVER edit a function, class, or method without first running `gitnexus_impact` on it. -- NEVER ignore HIGH or CRITICAL risk warnings from impact analysis. -- NEVER rename symbols with find-and-replace — use `gitnexus_rename` which understands the call graph. -- NEVER commit changes without running `gitnexus_detect_changes()` to check affected scope. - -## Resources - -| Resource | Use for | -|----------|---------| -| `gitnexus://repo/SuperBizAgent-java/context` | Codebase overview, check index freshness | -| `gitnexus://repo/SuperBizAgent-java/clusters` | All functional areas | -| `gitnexus://repo/SuperBizAgent-java/processes` | All execution flows | -| `gitnexus://repo/SuperBizAgent-java/process/{name}` | Step-by-step execution trace | - -## CLI - -| Task | Read this skill file | -|------|---------------------| -| Understand architecture / "How does X work?" | `.claude/skills/gitnexus/gitnexus-exploring/SKILL.md` | -| Blast radius / "What breaks if I change X?" | `.claude/skills/gitnexus/gitnexus-impact-analysis/SKILL.md` | -| Trace bugs / "Why is X failing?" | `.claude/skills/gitnexus/gitnexus-debugging/SKILL.md` | -| Rename / extract / split / refactor | `.claude/skills/gitnexus/gitnexus-refactoring/SKILL.md` | -| Tools, resources, schema reference | `.claude/skills/gitnexus/gitnexus-guide/SKILL.md` | -| Index, status, clean, wiki CLI commands | `.claude/skills/gitnexus/gitnexus-cli/SKILL.md` | - - diff --git a/CLAUDE.md b/CLAUDE.md index 6fb3118..44f7538 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -111,47 +111,3 @@ trailing off into the following information in 99% of cases: - 文档目录结构： - 不要将文档放到用户目录（如 `C:\Users\EDY\.claude\`）中 - - -# GitNexus — Code Intelligence - -This project is indexed by GitNexus as **SuperBizAgent-java** (1001 symbols, 2043 relationships, 78 execution flows). Use the GitNexus MCP tools to understand code, assess impact, and navigate safely. - -> If any GitNexus tool warns the index is stale, run `npx gitnexus analyze` in terminal first. - -## Always Do - -- **MUST run impact analysis before editing any symbol.** Before modifying a function, class, or method, run `gitnexus_impact({target: "symbolName", direction: "upstream"})` and report the blast radius (direct callers, affected processes, risk level) to the user. -- **MUST run `gitnexus_detect_changes()` before committing** to verify your changes only affect expected symbols and execution flows. -- **MUST warn the user** if impact analysis returns HIGH or CRITICAL risk before proceeding with edits. -- When exploring unfamiliar code, use `gitnexus_query({query: "concept"})` to find execution flows instead of grepping. It returns process-grouped results ranked by relevance. -- When you need full context on a specific symbol — callers, callees, which execution flows it participates in — use `gitnexus_context({name: "symbolName"})`. - -## Never Do - -- NEVER edit a function, class, or method without first running `gitnexus_impact` on it. -- NEVER ignore HIGH or CRITICAL risk warnings from impact analysis. -- NEVER rename symbols with find-and-replace — use `gitnexus_rename` which understands the call graph. -- NEVER commit changes without running `gitnexus_detect_changes()` to check affected scope. - -## Resources - -| Resource | Use for | -|----------|---------| -| `gitnexus://repo/SuperBizAgent-java/context` | Codebase overview, check index freshness | -| `gitnexus://repo/SuperBizAgent-java/clusters` | All functional areas | -| `gitnexus://repo/SuperBizAgent-java/processes` | All execution flows | -| `gitnexus://repo/SuperBizAgent-java/process/{name}` | Step-by-step execution trace | - -## CLI - -| Task | Read this skill file | -|------|---------------------| -| Understand architecture / "How does X work?" | `.claude/skills/gitnexus/gitnexus-exploring/SKILL.md` | -| Blast radius / "What breaks if I change X?" | `.claude/skills/gitnexus/gitnexus-impact-analysis/SKILL.md` | -| Trace bugs / "Why is X failing?" | `.claude/skills/gitnexus/gitnexus-debugging/SKILL.md` | -| Rename / extract / split / refactor | `.claude/skills/gitnexus/gitnexus-refactoring/SKILL.md` | -| Tools, resources, schema reference | `.claude/skills/gitnexus/gitnexus-guide/SKILL.md` | -| Index, status, clean, wiki CLI commands | `.claude/skills/gitnexus/gitnexus-cli/SKILL.md` | - -