跳到主要内容

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

⭐ Session 启动优先动作（FB-RESUME 协议）​

如果用户输入 按 SVA-9 + FB-RESUME 推进 或 按 FB-RESUME 推进，立即按下面顺序 hydration：

  1. 读 governance/workstreams/finbayes-arch-rewrite/CURRENT-MILESTONE.md（项目状态单一事实源）
  2. 读 governance/workstreams/finbayes-arch-rewrite/decisions/ADR-012-SVA-9-战略愿景对齐九层防御.md（如已落地）
  3. 读 governance/workstreams/finbayes-arch-rewrite/decisions/ADR-011-FB-RESUME-protocol.md
  4. 跑 git log --oneline -5 看最近动作
  5. ≤ 100 字回报当前 milestone / phase / active PR / 下一步 / 已知阻塞

任何 PR merge / milestone 切换 / P0 决议签字 / /compact 之前，主动 dump 状态到 CURRENT-MILESTONE.md 并 git commit（FB-RESUME 协议 §6）。

这是什么仓库​

Curvature Labs「FinTec AI 生态」的知识库 + 治理库，不是工程仓。仓库里 .md 是事实源，Docusaurus 渲染成公开站点，for-agents/ 是脚本派生出来给 Agent 看的副本。

99% 的情况：你只在改 Markdown​

  1. 找对位置（详表见 ACCESS.md）：「所有项目必须对齐的生态口径」→ ecosystem/；「跨项目能复用」→ commons/；「只是某项目自己的事」→ projects/<id>/；「协议 / ADR / 变更流程」→ governance/；外部材料或初步分析先进 commons/references/。从 commons 升 ecosystem 走 governance/change-protocol.md。
  2. 遵守正文规范（违反就构建失败）：frontmatter 必填 title / status / last-updated / scope / maturity；正文不写本地绝对路径；Markdown 链接显示文本要人可读（不能是 ../../foo.md）；单篇不混排中英文（默认中文，专名 / 代码标识 / URL 例外）；新概念先写进 ecosystem/glossary.md 再用。
  3. 提交前跑 npm run verify:kb（失败信息直指问题文件；子项可单跑 node scripts/verify-kb.mjs --only <glossary|site-nav|links|content-hygiene|agent>）。sidebar / 派生包 / 路由 / 索引由 npm run build 自动处理，不用操心。

不要碰的东西​

  • for-agents/：派生产物（scripts/derive-agent-pack.mjs）。要改 Agent 包，改源 .md 或派生脚本后跑 npm run derive，把派生差异一起提交。唯一例外：for-agents/topics/<id>/agent-pack.yaml 是人写的跨源聚合声明，仅维护对应 topic 时才动。
  • sidebars.js：构建时扫事实源自动生成，文档没上站去修文档位置 / README 标题，别手补 sidebar。
  • .omx/：Oh My Codex 本地运行态，已 gitignore，当不存在。

Graphiti 与本仓的关系​

Graphiti 是 Agent 的动态记忆和线索层，不是事实源：当线索看、不当事实，引用须标来源；值得长期保留的，人整理后走 governance/change-protocol.md 写回 Markdown 才算入库；两边不一致以本仓 Markdown 为准。

改水管（少见）+ 命令速查​

要求 Node ≥ 22。改派生逻辑 → scripts/derive-agent-pack.mjs；改校验规则 → scripts/verify-kb.mjs；改站点 / 导航 → src/、sidebars.js、docusaurus.config.js；改部署 → Dockerfile、nginx.conf、railway.json；改完跑 npm run build（含 prebuild 的 derive:check + verify:kb）。

常用命令：npm run start（dev）、npm run build（生产 + 索引）、npm run verify:kb、npm run derive（重派生写入）、npm run derive:check（只校验派生一致性）。pre-commit hook 自动跑 derive:check，过期阻断 → 先 npm run derive + git add for-agents/ 再重试 commit。

写入权限边界​

  • ecosystem/** 走 governance/change-protocol.md 生态级流程；projects/<id>/** 由对应项目 Controller 或被授权人提议、回写需评审；commons/** 新增自由（frontmatter 必填）；governance/** 所有改动留 ADR 在 governance/decisions/。
  • 工程执行产物（代码、运行日志、Controller state、handoff、task-packet）不进本仓，留在工程仓或私有运行环境。

当前进行中 + 公网​