Stats
Actions
Tags
From team-standards
Builds and queries backend knowledge graphs for single-service business logic (ER, SQL, state machines) and project-level technical pain points (concurrency, performance, external deps). Auto-captures facts during investigation.
How this skill is triggered — by the user, by Claude, or both
Slash command
/team-standards:backend-knowledge-graph-requiredThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
本 skill 负责 **后端单服务业务图谱 + 项目级技术难点图谱** 双重职责：
本 skill 负责 后端单服务业务图谱 + 项目级技术难点图谱 双重职责：
目标是让 AI 在后端接口开发前先理解：
长对话识别是项目级技术难点的最重要触发信号：用户在同一会话中对同一技术点反复疑问 / 多轮验证 / 出现回归性措辞，就是该技术点应当沉淀的强证据。AI 不必等用户显式说"记到知识图谱"，命中长对话模式即自动追加候选记录。
不处理前端 UI 或跨项目全局拓扑。跨项目链路仍交给 cross-project-locator。
下列任一场景命中即必须第一时间调起本 skill，先做候选沉淀路由判定，再继续答题或落盘。错过这些时机就是流程违反。
| 触发场景 | 命中信号 | 必做动作 |
|---|---|---|
Write/Edit 一份描述后端表关系 / ER / SQL / 状态扭转 / 业务流程 → 表 CRUD 的 .md（无论路径，包括 ai-docs/、work-log/、scenarios/ 而不仅 docs/） | 文档主体含表名 + 关联键 + SQL / DAO / Mapper + state/字段判定 + 数据流箭头 | 先按本 skill 决定归属命名空间和模板，再 Write |
| 用户问询表关系 / SQL 查询逻辑类问题 | "X 与 Y 是 1:1 还是 1:N"、"改这个动哪些表"、"字段从哪来"、"这个业务怎么查"、"这个 SQL 怎么写/完善"、"退款/账单/流水/分摊怎么算"、"是新建快照还是引用原表"、"哪个状态会变" | 答题同时把事实追加到候选沉淀池；涉及查询时同步记录 SQL 指纹候选 |
| AI 已完成后端代码调查并发现 ≥1 条可复用事实（含跨项目"以另一服务为调查对象"的场景） | 调查报告里出现具体表/SQL/DAO/Mapper/Service/枚举/状态值 | 调查结论给用户的同一回合，必须将事实候选追加到被调查项目命名空间下的候选池；有 SQL 时同步到查询索引候选 |
| 用户主动要求 | "建知识图谱"、"整理图谱"、"更新图谱"、"归档" | 先读候选池 + 现有正式图谱 + 代码证据，再写正式图谱 |
| 项目已有正式图谱 | 存在 docs/knowledge-graph/backend/ | 编码前必先回顾相关卡片，编码后必同步回写 |
| 后端代码变更 | 新增/修改 API、Service、DAO、SQL、表、枚举、状态机、事务边界、MQ、外部依赖 | 同步更新对应卡片或候选池 |
| 同一技术主题反复疑问 ≥3 轮（项目级技术难点） | 用户在同一会话中对同一技术点重复提问 / 验证 / 担忧 ≥3 次；或出现回归性措辞："为什么...还" / "怎么又..." / "上次说..." / "是不是...占用了" / "现在又卡了"；或修复后 ≥2 轮验证性追问 | 答题同一回合自动追加候选到 _candidates.md，分类标记 技术难点；超过 5 轮反复或用户显式提示"这是核心点"时主动起 scenarios/ 场景卡 |
| AI 完成涉及子进程 / 并发 / 性能 / 资源边界的代码改动 | 修复 transferTo 阻塞、Semaphore 限流、孤儿进程清理、缓存键策略、超时回收、磁盘/CPU 争夺等"非业务技术陷阱" | 编码后必候选记录；用户提示"这是难点要登记"时立刻整理为正式场景卡 |
会话首次 Write/Edit 后端业务源码（路径含 lib/features/{module}/backend(v\d+)?/**/*.dart 或 lib/common/backend_infra/(daos|services)/**/*.dart，非测试文件，非 ≤1 文件 ∧ ≤20 行的小改） | hook check-backend-kg-readiness.js PreToolUse 兜底（v1.28 起默认 warn 模式 exit 0 + stderr 提示，TEAM_STANDARDS_BACKEND_KG_HOOK=block 升级硬阻断、=off 关闭）；transcript 内 0 次 Read **/knowledge-graph/00_index.md 或 **/knowledge-graph/scenarios/*.md 或 **/knowledge-graph/ddl-baseline.md | 立即停止 Edit，先 Read 项目对应 knowledge-graph/00_index.md 按关键词反查命中场景卡再继续；命中场景卡也读完后才回到原 Edit |
即将写 SQL / 改 DAO / Mapper / Repository / Drift customSelect / Prisma raw query / JPA @Query，但项目 knowledge-graph/ddl-baseline.md 不存在 | 项目存在持久层代码（grep customSelect / @Query / @Repository / prisma.client / mysql.createConnection / pg.Client 等任一命中），但用户目录 + 项目 docs 两处的 knowledge-graph/ddl-baseline.md 都查不到 | 先 dump DDL 基线再写 SQL——按项目 DB 引擎选 dump 命令（详见下方「DDL 基线」节），把 schema 全景落到 knowledge-graph/ddl-baseline.md；不要凭 ORM 实体类反推 schema（实体类只展示子集，DEFAULT/INDEX/CHECK 等 schema 元信息容易丢失） |
常见误判反例（已发生过的踩坑）：
- ❌ "用户只是问云端逻辑，没让我建图谱，所以不用触发" → 错，问询场景必触发并候选沉淀
- ❌ "用户只是让我完善 SQL，所以只回答 SQL 就行" → 错，必须归档查询逻辑、涉及表、join/where/group by/order by、业务语义和复用原子能力
- ❌ "本地工程没有
docs/knowledge-graph/backend/，所以 skill 不适用" → 错，没有就先写候选池- ❌ "主目录是 A，调查的是 B 云端，应该交给 cross-project-locator" → 错，单服务图谱归属 = 被调查的那个服务，与 cwd 无关
- ❌ "我直接 Write 一份图谱文档就行了" → 错，写前必经本 skill 决定归属和模板
- ❌ "技术难点（子进程 / 并发 / 性能）不是表关系，所以不归本 skill" → 错，本 skill v1.21 起范围已扩到项目级技术难点；用户反复疑问的技术陷阱必须沉淀
- ❌ "用户没显式说'记到知识图谱'，所以不用沉淀" → 错，会话同主题反复疑问 ≥3 轮即自动触发，无需用户提醒；事后才记容易丢上下文
- ❌ "技术难点等下次会话再说" → 错，当场记录，错过即流程违反；会话结束后重新还原难点上下文成本极高
- ❌ "改 bug 直接 grep + Read 源码就够了，不需要先读图谱" → 错，v1.28 起
check-backend-kg-readiness.js在 PreToolUse 兜底提示；非小改的后端业务源码 Edit 前未读过knowledge-graph/00_index.md或场景卡即 hook 告警；图谱里的金额口径 / 状态判定 / SQL 指纹 / 原子能力索引能省去 grep 重复发明的轮次
核心规则：图谱归属永远 = 被调查的后端单服务项目，与当前主工作目录无关。
| 主目录 | 调查对象 | 图谱归属命名空间 |
|---|---|---|
| 本服务自身 | 本服务自身 | 本服务 |
| 项目 A（前端 / 调用方） | 项目 B（云端单服务） | 项目 B |
| 项目 A（前端） | 同时跨 A+B | A 的归 A、B 的归 B；纯跨项目链路（A 调 B 的对照映射、调用链）走 cross-project-locator |
候选池默认路径（被调查项目命名空间下）：
{USER_DOCUMENTS}/ai-docs/{被调查项目}/knowledge-graph/_candidates.md
{USER_DOCUMENTS}/ai-docs/{被调查项目}/knowledge-graph/scenarios/{场景}.md
{USER_DOCUMENTS}/ai-docs/{被调查项目}/knowledge-graph/00_index.md
正式图谱路径（用户明确要求"上传终版到项目内"才走）：
{被调查项目根目录}/docs/knowledge-graph/backend/...
判定本 skill vs cross-project-locator 的边界：
cross-project-locatorcross-project-locator 登记服务间链路后端接口开发不是只写接口文档，还必须沉淀表逻辑知识。
凡是本次开发涉及 DAO/Mapper/SQL、表状态、订单/退款/支付等业务判定、事务、锁、幂等或跨表组合查询，AI 必须把这些关系纳入后端知识图谱闭环：
编码前：先回顾表逻辑图谱 + 原子能力索引
编码中：优先复用已有原子能力 / DAO 原子查询
编码后：把新增或变更的表读写、状态变化、判定逻辑同步回图谱
如果项目尚无正式图谱，也不能让事实散落在会话里。必须写入用户目录候选池，至少沉淀“表逻辑候选记录”，后续确认或代码验证后再整理进正式图谱。
SQL 是后端知识图谱的一等资产。 只要会话中提到了某个业务查询逻辑、SQL、DAO/Mapper 方法、join 关系、过滤条件、聚合条件或排序分页规则，就必须沉淀为可合并的 SQL 指纹：
业务问题 → 涉及表/ER → SQL 指纹 → 原子能力 → 代码坐标 → 复用建议
SQL 图谱不追求保存一堆一次性 SQL 字符串，而是归档“业务查询能力”：
核心理念：第一份图谱只要 1 份场景卡 + 1 份扁平索引就算建立。 不要求 8 文件齐全才叫图谱——通过多个细小场景小卡渐进汇总成全景，是这套图谱的设计目标。
新建图谱时只需要这几个文件即可投入使用：
{命名空间根}/knowledge-graph/
00_index.md # 扁平索引：每个场景一行 + 关键词反查表
scenarios/{业务场景}.md # 一图一表的场景小卡（一图一表是底线）
_candidates.md # 候选沉淀池（未代码验证的会话事实）
_sql_candidates.md # SQL / 查询逻辑候选池（未正式合并的查询指纹）
ddl-baseline.md # ⭐ DDL 基线（涉及任何 DB 表读写的项目必有）
ddl-baseline.md 是涉及 DB 操作项目的硬必需，不是可选。 详见下方「DDL 基线」专节——
凡是项目里有 SQL / DAO / Mapper / Repository / Drift table / Prisma schema / JPA Entity 等
持久层代码，都必须配套有一份从真实 schema 源（sqlite_master / pg_dump / mysqldump 等）
dump 出来的 DDL 全景，让 AI 编写 SQL 前能一站式速查字段名 / 类型 / 默认值 / 索引，
避免凭记忆写出错误字段名引发的连环 bug。
每张场景小卡至少包含：
markdown-writing-standards）00_index.md 至少包含：
| 场景 | 主表 | 一句话 | 关键词 | 文件 |
|---|---|---|---|---|
| 退款数据模型 | refund_bill / pos_transaction / order_item / order_item_payment_allocate | 1 bill + N tx + 新建 item 快照 + 按 tx 比例分摊 | 退款 / 账单 / 流水 / 分摊 / 部分退 | scenarios/退款数据模型.md |
当已有 ≥3 张场景小卡，且发现表 / 枚举 / 流程 / 原子能力被多个场景共享时，再单独建以下卡片：
{命名空间根}/knowledge-graph/
tables/{table-name}.md # 高频被多场景引用的表
enums/{enum-name}.md # 高频枚举字典
flows/{flow-name}.md # 跨多场景的业务流程
atomic-capabilities/{cap}.md # 被多接口复用的原子能力
07_table_logic_index.md # 表逻辑反查索引（场景多了再建）
08_atomic_capability_index.md # 原子能力索引（能力多了再建）
09_sql_query_index.md # 原子能力 ↔ SQL 查询逻辑索引（查询多了再建）
sql-queries/{business-scenario}.md # 按业务场景合并后的 SQL 查询卡
仅在图谱规模足够大、需要给 AI 做"先读图谱再读代码"门控时再补：
{命名空间根}/knowledge-graph/
00_backend_service_profile.md # 服务画像
01_domain_capability_map.md # 领域能力地图
02_data_model_map.md # 数据模型总览
03_enum_dictionary.md # 枚举总字典
04_api_entrypoints.md # API 入口总表
05_external_dependencies.md # 外部依赖
06_business_flow_index.md # 流程总索引
| 阶段 | 命名空间根 | 何时使用 |
|---|---|---|
| 候选 / 草稿 | {USER_DOCUMENTS}/ai-docs/{被调查项目}/knowledge-graph/ | 默认；AI 起草、未确认、未代码验证 |
| 正式 | {被调查项目根目录}/docs/knowledge-graph/backend/ | 用户明确要求"上传终版到项目内"才走，遵循 doc-index-required |
入门门槛兜底：项目尚未有任何图谱时，本 skill 第一次落盘只产出 Tier 1 的最小文件即可（00_index.md + 1 张 scenarios/{xxx}.md + _candidates.md；若本次涉及 SQL，再加 _sql_candidates.md），不要一次性铺满 Tier 3。
SQL 图谱同样按渐进方式建立：
| 阶段 | 文件 | 何时创建 |
|---|---|---|
| 候选 | _sql_candidates.md | 任意会话提到业务查询、SQL、DAO/Mapper 查询逻辑时立即追加 |
| 索引 | 09_sql_query_index.md | 同一项目累计 ≥3 条 SQL 候选，或用户要求“整理 SQL / 完善 SQL / 归档查询逻辑”时创建 |
| 场景卡 | sql-queries/{business-scenario}.md | 同一业务场景存在 ≥2 条查询，或一个 SQL 涉及 ≥3 张表 / 聚合 / 状态判定时创建 |
| 全景 ER | 02_data_model_map.md + tables/{table}.md | 累计 ≥5 张核心表，或用户要求“全景 ER 图”时创建 / 更新 |
SQL 候选不可长期散落。 当用户要求“整理 / 归档 / 完善 SQL”时，必须先读取 _sql_candidates.md、09_sql_query_index.md、命中的 sql-queries/ 与表卡，然后去重合并，更新正式索引和场景卡。
核心约定：凡是项目里有任何持久层代码（SQL / DAO / Mapper / Repository / Drift table / Prisma schema / JPA Entity 等），知识图谱必须配套一份 knowledge-graph/ddl-baseline.md，作为 SQL 编写、字段语义、索引信息的权威源。
Why（为什么是 DDL 而不是 ORM 实体类）：
Table / JPA @Entity / Prisma model 通常只声明列名 + 类型，DEFAULT 值、NULL 约束、复合索引、CHECK 约束、FOREIGN KEY 行为等 schema 元信息容易遗漏或脱节order_transaction 表无 order_id 字段"等踩坑案例触发条件：
| 项目特征 | 是否需要 ddl-baseline.md |
|---|---|
项目有任何 customSelect / 裸 SQL 字符串 | 需要 |
| 项目用 ORM 但 service 偶尔写 raw query | 需要 |
| 项目纯 ORM、所有查询走 typed query builder | 强烈推荐（仍能从 DDL 看到索引、默认值、约束） |
| 项目无 DB（如纯前端 / 纯计算服务） | 不需要 |
标准路径与命名：
{命名空间根}/knowledge-graph/ddl-baseline.md
不要拆 ddl/{table}.md——分散后失去"一次 Read 拿全景"的核心价值。表多到一份文件不便读时，可在文档内按业务域分章节，但单文件原则不变。
dump 命令模板（按 DB 引擎）：
| DB 引擎 | dump 命令 |
|---|---|
| SQLite | python -c "import sqlite3; con=sqlite3.connect('path/to.db'); [print(r[0]+';\n') for r in con.execute(\"SELECT sql FROM sqlite_master WHERE sql IS NOT NULL AND name NOT LIKE 'sqlite_%' ORDER BY tbl_name\").fetchall()]" 或 sqlite3 path/to.db .schema |
| PostgreSQL | pg_dump --schema-only --no-owner --no-privileges $DATABASE_URL |
| MySQL | mysqldump --no-data --skip-add-drop-table --compact $DATABASE > schema.sql |
| MSSQL | sqlcmd -S server -d db -Q "..." -E -o schema.sql（按需写脚本） |
| Oracle | expdp ... CONTENT=METADATA_ONLY 或 SQL Developer 导出 schema |
如果项目用 Drift / TypeORM / Prisma / Diesel 等 schema-as-code 框架，原则上 source of truth 是 framework 文件——但仍然要 dump 一份真实 DB 实例（dev 或 test 环境）的 schema 作为 ddl-baseline，因为 framework 文件不展示 schema 历史迁移叠加后的真实形态。
文档结构要求：
# DDL 基线 · {项目名} {DB 类型} schema
> 用途：编写 SQL / 改 DAO / 设计接口前 **必读** 的权威 schema 源。
> 数据源：{真实 DB 路径 / 连接信息（脱敏）}，按 {sqlite_master / pg_dump / mysqldump} 实时 dump。
> 表数量：{N} 张表 + {M} 个索引
> 更新时机：项目 schema 迁移后重新 dump（脚本见文末「维护脚本」段）
>
> **强约束**：编写任何 SQL 前必须先读本文档对应表段——确认字段名 / 类型 / 默认值 / 索引；
> 不要凭记忆写表/字段名。
## 表清单（按字母序 / 按业务域）
... TOC 链接 ...
## {table-name}
\`\`\`sql
CREATE TABLE ... ;
CREATE INDEX ... ON ... ;
\`\`\`
## 维护脚本
\`\`\`bash
{dump 命令}
\`\`\`
维护时机：
no such columntables/{table}.md（业务语义注解卡，Tier 2）的关系：DDL 是源，tables 卡是注解——tables/{table}.md 引用 DDL 中相应字段并补业务含义、读写能力、状态语义等，禁止重复抄一份 CREATE TABLE~/scripts/ 或 IDE workspace 根目录（不入 git 仓库），避免脚本里硬编码 DB 连接信息泄漏hook 集成：
check-backend-kg-readiness.js PreToolUse hook（v1.28 起默认启用）的"已读图谱"字面量白名单包含 knowledge-graph/ddl-baseline.md——AI 写 SQL 前 Read 一次 DDL 基线即满足 hook 兜底条件。
开始分析或实现后端接口前，只要本次涉及数据库读写、状态判定、订单/退款/支付等业务对象，必须先按顺序回顾：
ddl-baseline.md：按目标表名直接定位 CREATE TABLE / INDEX，确认字段名 / 类型 / 默认值 / 索引（涉及 DB 操作的项目此项跳不过）07_table_logic_index.md：按业务对象/场景反查表关系和判定规则08_atomic_capability_index.md：按业务关键词反查可复用原子能力09_sql_query_index.md：按业务关键词 / 表名 / DAO 方法反查已有 SQL 查询逻辑table-logic/{scenario}.mdatomic-capabilities/{capability}.mdsql-queries/{business-scenario}.mdtables/{table-name}.md、flows/{flow-name}.md、enums/{enum-name}.md若上述文件不存在，应在设计/编码过程中创建用户目录候选记录，不得因为“还没建图谱”就跳过沉淀。
写后端 Service / Handler / UseCase 主流程时，必须主动判断：
| 问题 | 正确动作 |
|---|---|
| 已有表逻辑图谱说明了该判定 | 按图谱回到代码坐标复用，不重新发明规则 |
| 已有原子能力覆盖该计算/查询 | 注入/调用原子能力，禁止复制 SQL 或业务计算 |
| 只有 DAO 原子查询，没有业务原子能力 | 优先复用 DAO；若本次组合逻辑会被多接口复用，沉淀新原子能力 |
| 发现旧代码有重复判定 | 本次改动范围允许时抽出原子函数；否则登记“待抽取原子能力”候选 |
已有 09_sql_query_index.md 命中类似 SQL | 复用现有 DAO/Mapper/SQL 指纹，只补差异条件，不重新拼一份相似查询 |
典型原子能力包括但不限于：
当用户要求“完善 SQL”或 AI 需要新增 / 修改查询时，必须按以下顺序处理：
09_sql_query_index.md → sql-queries/ → tables/ / 02_data_model_map.md_sql_candidates.md 或正式 09_sql_query_index.md / sql-queries/SQL 完善输出时必须显式说明：
SQL 完善依据：
- 业务问题：
- 复用 / 参考的原子能力：
- 涉及表与 ER 关系：
- 新增或调整的 join / where / group by / order by：
- 状态 / 枚举 / 金额字段语义：
- 索引风险：
- 需回写图谱：
后端源码改动完成后，只要命中以下任一项，必须更新正式图谱或候选池：
回写最少包含：
- 本次接口 / 能力名称
- 涉及表与读写动作
- 表之间业务关系
- 状态字段变化或判定规则
- 可复用原子能力 / DAO 方法
- 代码坐标
- 对后续新增接口的支持判断
为避免会话中的业务事实遗漏，后端知识图谱采用“两段式沉淀”：
会话提及 / 代码分析发现
→ 自动记录到候选沉淀池
→ 用户确认或证据校验
→ 整理进入正式知识图谱
候选沉淀池默认写入用户目录被调查项目命名空间下，不写项目 docs/：
{USER_DOCUMENTS}/ai-docs/{被调查项目}/knowledge-graph/_candidates.md
{USER_DOCUMENTS}/ai-docs/{被调查项目}/knowledge-graph/_sql_candidates.md
说明：v1.18.7 起候选池路径精简为
_candidates.md（按被调查项目而非按日期/agent 分），便于跨日期跨会话累积同主题事实并最终归并到 scenarios 卡。旧版{agent}/{YYYY-MM-DD}/backend-kg-candidates.md路径仅作向后兼容，不再推荐新增。
自动追加规则（强制）：
AI 在会话中只要回答了任何关于后端表关系 / 业务判定 / 状态扭转 / 字段语义的问题，即便用户没要求"建图谱"，回答的同一回合内必须自动追加 1 条候选记录到 _candidates.md。这是本 skill 的最低收口动作——错过即流程违反。
AI 在会话中只要回答了任何关于 SQL / DAO / Mapper / 查询逻辑 / 过滤条件 / join / 聚合的问题，同一回合还必须自动追加 1 条 SQL 候选记录到 _sql_candidates.md。如果答案里出现了 SQL 代码块、伪 SQL、查询字段清单、表 join 说明或 DAO 方法名，就视为命中。
候选池用于防遗漏，正式图谱用于可信引用。二者职责必须分开。
每条候选记录最少格式：
## YYYY-MM-DD HH:MM | {场景关键词}
- 事实：{一句话业务事实}
- 涉及：{表/枚举/状态字段}
- 来源：{代码坐标 or 用户描述 or 设计文档 or 调查报告}
- 可信度：待确认 / 已确认 / 已代码验证
- 后续动作：{待用户确认 / 待代码核验 / 可整理入正式 scenarios 卡}
SQL 候选记录最少格式：
## YYYY-MM-DD HH:MM | {业务问题 / 查询能力}
- 业务问题：{这个 SQL 回答什么问题}
- SQL 指纹：{SELECT 主字段 FROM 主表 JOIN ... WHERE ... GROUP BY ... ORDER BY ...，可脱敏 / 参数化}
- 参数：{入参及业务含义}
- 返回字段：{字段及业务含义}
- 涉及表：{主表、关联表、关联键}
- 过滤 / 聚合 / 排序：{where/group by/having/order by 的业务语义}
- 状态 / 枚举：{字段值与枚举含义}
- 原子能力：{DAO/Mapper/Repository/Service 方法，未知则写待定位}
- 代码坐标：{文件:行 / 方法名，未知则写待定位}
- 索引建议：{可能需要的索引，未知则写待评估}
- 可信度：待确认 / 已确认 / 已代码验证
- 合并目标：`09_sql_query_index.md` / `sql-queries/{场景}.md` / `tables/{table}.md`
整理 SQL 图谱时，必须先按“SQL 指纹”去重，而不是按原始字符串去重：
| 合并维度 | 说明 |
|---|---|
| 业务问题 | 同样回答“订单可退金额 / 退款流水池 / 账单明细查询”等问题的 SQL 归为同一查询能力 |
| 主表 + 关联表 | 主表相同、join 链路相同，只是 where 条件不同，合并为同一 SQL 卡的变体 |
| 过滤语义 | deleted=0、租户/门店、状态枚举、时间范围、金额方向等按语义归并 |
| 聚合语义 | sum/count/max 等聚合按“业务指标”命名，避免只写表达式 |
| 原子能力 | 同一 DAO/Mapper/Service 方法产生的 SQL 必须归到同一原子能力下 |
合并后保留：
分析后端需求前，按图谱所在层级读取（命名空间 = 草稿 ai-docs/{项目}/knowledge-graph/ 或 正式 docs/knowledge-graph/backend/）：
Tier 1 起步阶段（仅有 00_index.md + scenarios/ + _candidates.md）：
00_index.md：按关键词反查命中的场景小卡scenarios/{业务场景}.md_candidates.md：扫一遍候选池，看本次主题是否已有未确认事实Tier 2/3 成熟阶段（已有细分卡片）按以下顺序：
00_index.md → 00_backend_service_profile.md（如有）01_domain_capability_map.md、06_business_flow_index.md（如有）07_table_logic_index.md、08_atomic_capability_index.md（如有）09_sql_query_index.md（如有）scenarios/{场景}.mdtable-logic/{scenario}.md、atomic-capabilities/{capability}.md、sql-queries/{business-scenario}.mdcapabilities/{capability}.md、flows/{flow}.mdtables/{table}.md、enums/{enum}.md、02_data_model_map.md04_api_entrypoints.md、05_external_dependencies.md（如有）_candidates.md、_sql_candidates.md不得在已有图谱可定位时直接全量扫描代码。即使图谱只有 Tier 1，也要先读 00_index.md 和命中的场景小卡。
后端能力必须区分三类：
| 类型 | 定义 | 示例 |
|---|---|---|
| 原子能力 | 可复用的最小业务能力 | 生成订单号、校验商品、计算价格、锁库存 |
| 领域能力 | 围绕一个业务对象完成一项完整动作 | 创建订单、取消订单、支付订单 |
| 编排能力 | 跨多个领域能力/外部依赖的流程编排 | 下单履约流程、支付后出单流程、退款流程 |
能力卡必须写清能力类型，禁止把所有 Service 方法都叫“原子能力”。
后端单服务知识图谱正式落盘的 10 类卡片模板：表逻辑总索引 / SQL 查询索引 / SQL 查询卡 / 原子能力索引 / 表逻辑卡 / 原子能力卡 / 能力卡 / 流程卡 / 表卡 / 枚举卡。
详细模板见 rules/card-templates.md。写正式图谱时按需选用对应模板;写候选池
_candidates.md/_sql_candidates.md时模板更轻,见下方「会话沉淀规则」节。
用户在会话中经常提到的内容必须自动记录到候选沉淀池，但不能无条件自动写入正式知识图谱。按以下规则处理：
| 场景 | 处理 |
|---|---|
| 用户明确说“记入知识图谱 / 更新知识图谱 / 归档到后端图谱” | 先检索候选池 + 现有正式图谱，再整理更新正式图谱 |
| 本次后端代码变更新增/修改 API、Service、DAO/Mapper/SQL、表、枚举、状态流转、MQ、外部依赖 | 必须更新相关图谱卡片或候选池 |
| 本次后端代码涉及订单/退款/支付等表逻辑判定 | 必须更新 07_table_logic_index.md / table-logic/ / 08_atomic_capability_index.md 中至少一处 |
| 会话中反复出现同一后端业务事实，但尚未代码验证 | 自动追加到候选沉淀池，默认写用户目录，不进正式图谱 |
| 同一会话同一技术主题用户反复疑问 ≥3 轮（含直接提问 / 验证性追问 / 担忧性表达 / 回归性措辞） | 自动追加候选记录，标记 分类: 技术难点；超过 5 轮反复或用户显式提示"这是核心点"时直接生成 scenarios/ 场景卡 |
| 用户出现回归性措辞（"为什么...还"、"怎么又..."、"上次说..."、"是不是...占用了"、"现在又卡了"） | 视为技术难点信号，自动追加候选 |
| 修复后用户提出 ≥2 轮验证性追问（"是不是真的解决了"、"会不会再出现"、"还有没有其它"、"重启后还会有么"） | 答题同回合追加候选，标注 "已修复 + 验证关注点"，便于下次回归测试覆盖 |
| 涉及子进程 / 并发 / 性能 / 资源边界 / 外部依赖编排的非业务代码变更 | 编码后必候选记录到 _candidates.md，分类 技术难点；本身就是项目重点资产 |
| 事实来自代码、DDL、枚举类、接口契约、已确认设计文档 | 可作为正式图谱依据；更新前仍需合并候选池同主题内容 |
| 只是猜测、临时讨论、未确认方案 | 可记录为“待确认假设”，禁止写入正式图谱 |
正式图谱条目必须能追溯到至少一个来源：代码坐标、表结构、枚举类、接口契约、设计文档或用户明确确认。
候选沉淀池每条记录至少包含：
- 记录时间
- 服务/模块
- 分类：业务事实 / 技术难点 / 性能 / 资源 / 进程 / 并发 / 运维 / 其它
- 会话事实
- 关联能力/流程/表/枚举/外部依赖
- 触发模式：用户主动要求 / 长对话同主题 ≥3 轮 / 修复后验证追问 / 代码改动后自动归档 / ...
- 可信度：待确认 / 已确认 / 已代码验证
- 来源：用户描述 / 代码坐标 / DDL / 枚举类 / API 契约 / 实战 bug
- 后续动作：待用户确认 / 待代码核验 / 可整理入正式图谱
当用户后续要求“整理知识图谱 / 更新正式图谱 / 归档”时，必须先读取：
_candidates.md、_sql_candidates.mddocs/knowledge-graph/backend/ 现有正式图谱09_sql_query_index.md、sql-queries/、02_data_model_map.md、表卡、原子能力卡然后去重、合并、补证据，再写正式图谱。
后端源码出现以下变化时，应同步检查知识图谱：
若项目没有正式 docs/knowledge-graph/backend/，先在用户目录生成“知识图谱更新建议”和表逻辑候选池；用户确认后再写正式图谱。
若项目已有正式 docs/knowledge-graph/backend/，且本次代码变更已验证事实，应直接更新命中的正式卡片；不确定内容写入候选池。
当用户询问或 AI 自己需要判断“新增接口是否支持”时，必须基于表逻辑图谱回答：
输出格式：
后端表逻辑支持性：
- 结论：支持 / 部分支持 / 不支持
- 依据表：
- 依据状态/枚举：
- 可复用原子能力：
- 缺口：
- 需更新图谱：
多项目知识图谱不做单服务内部能力的重复整理，主要记录服务间关系：
跨项目链路交给 cross-project-locator。本 skill 只在单服务图谱中保留“外部依赖”视角，不把多个项目的内部表、枚举、原子能力混到一起。
执行后端知识图谱分析或更新时，必须回显：
后端知识图谱：
- 项目：
- 命中能力：
- 读取图谱：
- 命中 ER / 表关系：
- 命中表逻辑：
- 命中 SQL 查询：
- 可复用原子能力：
- 需更新图谱：
- 更新依据：
- 输出路径：
| 错误想法 | 正确处理 |
|---|---|
| “用户提到了就写入正式图谱” | 先自动进候选沉淀池，确认或代码验证后再整理入正式图谱 |
| “不自动记录，等用户以后想起来再说” | 错。会话中的后端业务事实应自动候选记录，防止遗漏 |
| “一个 plugin 把所有端都做了” | 本 skill 只管后端单服务，不管前端 UI 或跨项目全局拓扑 |
| “先全量扫代码再说” | 有图谱先读图谱，再按代码坐标读文件 |
| “表字段照抄一遍就算图谱” | 必须写字段业务含义、读写能力和一致性约束 |
| “SQL 回答完就结束” | 必须同步沉淀 SQL 指纹、业务问题、涉及表、join/where/group by/order by 语义和原子能力 |
| “全景 ER 等最后再画” | 当用户要求全景 ER 或核心表累计到一定规模时，必须更新 02_data_model_map.md，并从 SQL / 表卡反推关系 |
| “同一个业务查询换个 where 就另建一份 SQL” | 按 SQL 指纹合并，作为同一查询能力的变体，不制造重复卡 |
| “订单部分退这类规则问过很多次但不用沉淀” | 错。反复出现的表逻辑、状态判定、金额聚合必须进入表逻辑候选池或正式图谱 |
| “写新接口时直接再查一遍 SQL” | 先查 07_table_logic_index.md、08_atomic_capability_index.md 和 09_sql_query_index.md，已有 SQL / 原子能力直接复用 |
| “Service 里临时复制一段表判定最快” | 应优先复用原子能力；确需临时兼容时登记待抽取原子能力 |
| “枚举值不用单独整理” | 后端需求分析必须显式读取相关枚举卡 |
| “跨项目链路也写这里” | 单服务只记录本服务视角；跨项目交给 cross-project-locator |
| “ffmpeg / 子进程 / 性能 / 资源争夺这些是技术坑，不是表关系，不归图谱” | 错。v1.21 起范围已扩到项目级技术难点；反复出现的非业务技术陷阱同样必须沉淀 |
| “用户没显式说'记到知识图谱'，那就先不记” | 错。同主题 ≥3 轮反复疑问、回归性措辞、修复后验证追问，都是自动触发条件，无需用户提醒 |
| “技术难点等下次会话再说” | 错。当场记录是硬规则，错过即流程违反；会话结束后还原难点上下文成本极高 |
| “修复了就完事了，不用记" | 错。修复后用户多轮验证追问 = 这是项目持续关注的难点，必须沉淀供下次回归参考 |
npx claudepluginhub exception-coder/team-standards --plugin team-standardsProvides behavioral guidelines to reduce common LLM coding mistakes, focusing on simplicity, surgical changes, assumption surfacing, and verifiable success criteria.
Searches, retrieves, and installs Agent Skills from prompts.chat registry using MCP tools like search_skills and get_skill. Activates for finding skills, browsing catalogs, or extending Claude.
Creates, edits, and optimizes skills for Claude Code, including drafting, evaluating with test prompts, iterating on performance, and improving skill descriptions for better triggering accuracy.