Skip to content

CLAUDE.md

Latest commit

 

History

History
95 lines (83 loc) · 10.6 KB

CLAUDE.md

File metadata and controls

95 lines (83 loc) · 10.6 KB
Raw

CLAUDE.md — AI协作项目全生命周期框架

项目类型：本仓库是方法论文档项目，核心交付物为单份 Markdown 文档（~16 万字符）及其结构化配套（JSON / DOCX），非软件项目，无单元测试。CI 流水线包括翻译漂移检测（translation-drift.yml）和 Pages 部署（pages.yml）。_workflows/ 下的 .py 脚本仅为文档生成/同步/验证工具，不做无关重构。

Agent 边界

  • 可派：按框架 SOP 执行审查/试读/试跑；按 §8.8 S/M/L 分档执行闭合；按 §1.7 原则评估新增内容是否应外挂
  • 禁止：修改核心机制（未经试跑回写）；OPEN 项最终裁决；框架级成熟度评估独立复核（需异后端）；GitHub 发布执行
  • 审查独立性硬约束：禁止用框架编写时的同一后端模型审查框架（违反 §9.2）——同一后端换 CLI 壳=伪独立。当前可用的异后端清单见 project_status.md，不可在 CLAUDE.md 中维护模型白名单（易变信息，违反缓存友好原则）
  • 审查任务入口：执行独立审查前必须先读 _protocols-and-tools/methodological-review-sop.md（v1.0.4）
  • Provenance 级别：用户给定修改方向、Agent 只执行编辑时，独立性不得标 [IND]，按 §9.2/§14 记录为 [SEMI-ED] 或相应编辑级别

环境与命令

  • 运行环境：Windows 11 + Git Bash；Python 3.12；Node.js（mmdc 需要）；pandoc（DOCX 生成）；OpenCC（正體中文转换）
  • Python 中文脚本必须设 PYTHONIOENCODING=utf-8，路径全部用正斜杠
  • LSP 优先约束：本项目已配置 .lsp.json（pyright）。代码理解任务必须优先考虑内置 LSP 工具（goToDefinition、findReferences、hover、documentSymbol）。选择策略如下：
    • 必须 LSP（语义理解，grep 无法可靠判定）：找语义引用（需排除注释/字符串/同名局部变量；若目标是字面出现或文本提及则用 grep）、跳转定义（需解析 import/继承/作用域）、类型/签名查询、继承/接口关系理解。若当前工具集不支持实现跳转，先用 LSP 获取定义/类型再 grep 缩小候选。语义级操作的准确性需求优先于文件量阈值
    • 倾向 LSP（正则精度不够或范围较小，约 ≤5 文件）：正则易误匹配的场景、单文件/少量文件。若 LSP 已就绪可顺带查看 pyright 诊断；若 LSP 不可用/未就绪/超时，应记录回退原因
    • 倾向 grep（纯模式匹配 + 正则精度极高 + 文件量大 >5）：^def 搜函数定义、^import |^from 搜导入、TODO/FIXME 标记搜索等——一次调用覆盖全量文件，远快于逐文件 LSP。正则精度判断标准（针对 Python 语法）：行首锚定 + 关键字唯一 + 误匹配概率低且对任务可接受；若搜索结果将驱动修改应抽样核验。若无法快速判断精度，默认走 LSP。当任务同时属于必须 LSP 类别时，此条不适用
    • 混合策略：同一任务可组合 grep 和 LSP。典型模式：grep 批量收集候选文件/行号 → LSP 对候选精确验证定义/引用/类型。透明度规则中分别列出即可
    • 非代码理解任务（纯文本搜索）直接 grep，不触发 LSP 优先
    • 透明度规则：每次代码理解任务的最终答复开头，保留一行工具选择说明。格式：[工具] LSP:goToDefinition ×3 + Grep ×1 | 理由: 跳转定义需语义(3处)；候选文件收集用正则一次覆盖。若因 LSP 不可用而回退 grep，须写明回退原因。非代码理解的纯文本搜索无需标注
  • 关键命令： 
    bash check.sh                      # 发布前机械闸门（P0 门，唯一推荐入口）
python verify_version_consistency.py --skip-archive  # 全项目版本一致性验证
python _workflows/regenerate_docx.py    # 全量重生成 .docx（pandoc + Mermaid）
python _workflows/regenerate_inventory.py  # 重生成 inventory.csv
    不要直接跑 python pre_push_check.py——环境变量不设会漏扫项目绝对路径。除调试外一律用 bash check.sh。
  • DOCX 生成管道详情见 _workflows/；翻译管道见 _workflows/i18n/
  • 版本号单一事实源：VERSION 文件；主文档 §14 为完整 edit_history。勿在 CLAUDE.md 中维护版本号副本

快速恢复

按顺序先读：

  1. 本文件（CLAUDE.md）
  2. project_status.md ——从文件末尾往前读（追加式日志，顶部为旧会话，最新状态在末尾 "当前阶段/Next Steps" 附近）
  3. 主文档 §1.4–§1.7 ——使用强度分档 + 死亡判据 + OPEN 项 + §1.7 最小核心原则
  4. _protocols-and-tools/框架级成熟度评估表.md ——了解各部分成熟度，避免高估不稳定组件
  • 需要定位特定文件时：reference_files.md（人类标注版文件索引，标注了每个文件"为什么重要"——Glob 可列文件名，但给不了这个判断）

节号稳定性：本文档大量引用主文档节号（如 §X.Y）。编辑主文档（增删章节/调整编号）后，须验证 CLAUDE.md 中所有节号引用是否仍然有效。

停止条件

  • "试跑"在本项目中的定义：按框架指导完整执行一个 AI 协作项目周期（通常 ≥4 小时），不是运行某个脚本。试跑记录须写入 _reviews/。Agent 禁止将"脚本跑通"等同于"已验证"
  • 新增 [Sp] 节或修改核心机制 → 须先经过 ≥1 次试跑验证，不可仅凭方法论提取就写入。冻结期已于 2026-06-16 解除，但其核心教训——"加复杂度比减复杂度容易"——仍作为操作约束保留
  • 不用作者模型自审框架（违反 §9.2 独立性）
  • 不混淆编辑者与审查者角色——编辑判断仍需异后端独立复核
  • OPEN-4（试读计时）或 OPEN-1（人类专家 verify）未确认前 → 不启动大规模第二次试跑
  • 涉及 OPEN 项相关章节的修改 → 须先确认该 OPEN 项是否已关闭。完整 OPEN 项列表见主文档 §1.6
  • 三件套（.md / .json / .docx）同步：修改顺序——先 .md → 再 .json（结构化镜像）→ 最后 .docx（全量重生成）。DOCX 生成失败后须回滚 JSON 变更或标记"部分同步"。任一件修改后须触发 ≥1 轮异后端交叉验证
  • 主文档或 README 公开内容修改后 → 必须同步 zh-Hant/ 和 en/ 译文，或明确在 project_status.md 记录译文未同步状态。CI 的 translation-drift.yml 监控根 README 变更，14 天漂移阈值
  • 不要用 _protocols-and-tools/import_integrity_check.py ——经审查认定不可靠。正确工具：pyflakes / ruff

已知坑位

易误解概念

  • "使用强度分档"（§1.4 A/B/C）≠ "项目规模分档"（§8.8 S/M/L）——两个正交维度，用完不能互换
  • "独立审查"双轴定义（§9.2）：后端模型不同 × 上下文隔离，两者必须同时满足。审了作者 memory/CLAUDE.md = 上下文未隔离 = [SEMI] 或 [NON]
  • "Claude"在 provenance 上下文中 = CLI 壳名，不是后端模型——后端需当场记录，不可事后恢复
  • §1.7 "最小核心 + 示例外挂"存在自反风险——框架自身是否遵守了这一原则尚无独立验证

易误操作

  • 标识/路径清理仅限发布包：.gitignore 定义了发布边界。../开源发布准备/ 和 ../_attic/ 不在发布范围内，无需清理
  • OPEN 项状态变更只改 §1.6 一处（单一事实源原则）
  • 所有编辑必须记录 provenance（编辑者模型 + CLI 壳名 + 日期 + 独立性级别）→ 写入主文档 §14 和 JSON edit_history
  • 主文档和主 JSON 须同步更新——JSON 是手工维护的结构化镜像（非全量生成），每版需新建 sync 脚本或手工补入。历史：v1.6.2–v1.6.4 的 .json sync 落后于 .docx sync，靠事后脚本补回。同步顺序：.md → .json → .docx
  • Mermaid 渲染 PNG 不带 DPI 元数据——Word 默认 96 DPI 致 ~3× 拉伸截断。生成后须注入 300 DPI
  • _pipeline_output/ 和 _mermaid_png/（PNG 渲染缓存部分）是脚本自重建目录——内容为空不代表文件缺失，勿试图"修复"
  • 归档旧文件时须同步更新 README.md / reference_files.md / inventory.csv 中的交叉引用

跨项目行为制约

每条是框架中特定节的操作限制——来源项目的质量直接约束该节的可升级性（以下约束可从主文档推导，但推导链条长、误判代价高，故显式列出）：

  • Evolver（混淆代码项目） → 四个 [Sp] 节（§3.7.0 / §3.7.4.1 / §9.7 / §9.8）来源可信度低 → 禁止未经试跑将其从 [Sp] 升级，即使有新证据也要从 [Sp] → [E-] 起步
  • PocketFlow / prompt-tdd 实验链 → §6.3.2 [E-] ceiling-limited + 附录 H 反模式 → 修改这些节时遵守已有证据上限，不可超出实验覆盖范围
  • BDC2026（反面案例） → §7 会话交接 + §8 风险依赖的设计依据 → 不可弱化这两节，不可将 "会话交接缺失致败" 的教训降级为可选
  • 方法论提取 / Protocol 3 → "试跑 → 回写"是框架核心机制 → 所有机制变更必须遵循此模式

跨仓库传播

当前 7 个公开仓库的传播关系（2026-07-17 更新）：

  • ai-collaboration-framework（本仓库）← 方法论上游，规范版
  • independent-review-toolkit ← 提取自本仓库 §9.2，独立版本
  • prompt-tdd-methodology ← 提取自本仓库 §4.1.1，独立版本
  • ma-case-study-pipeline ← 框架六层理念的实证案例
  • etf-pattern-match-pybind11 ← 采用本框架的多后端审查/被动观测/项目闭合协议
  • docx-pipeline ← 从本仓库 DOCX 生成管道提炼的独立工具
  • claude-skills ← 从本仓库 §9.2-§9.3 提炼的 Claude Code 技能集合
  • 新增仓库或变更关系时，须同步更新本段 + 各仓库底部的交叉链接表

更新协议

  • 触发条件：试跑完成后 / OPEN 项状态变更 / 外部方法论提取写入 / 三件套任一件更新 / README 版本号或统计区变更 / 新增或重命名文件 / 新增仓库或仓库关系变更
  • 更新后必做：同步 README.md 版本号和统计区 + JSON metadata 版本/日期 + reference_files.md（文件增删/重命名后须更新人类标注索引并验证路径准确性）
  • 本文件（CLAUDE.md）仅在操作指令变更时才修改——不因 README 版本号/统计变化而机械更新（减少 prompt cache 失效）
  • 新增内容优先外挂（附录或独立文件），不直接进核心章节——§1.7 自反要求
  • 重大版本变更后 → 触发 ≥1 轮异后端交叉验证
  • 所有编辑遵守 §14 provenance 记录纪律