449 lines
24 KiB
Markdown
449 lines
24 KiB
Markdown
# CLAUDE.md
|
||
|
||
> [!URGENT]
|
||
> **科研工程混合 + 生产级项目（非 MVP）**
|
||
> 1. 本项目是科研工程混合体（当下工程为主，后续 Agent 进化科研为主），要求**生产级**的稳定性、并发性、防御性、可观测与测试。YAGNI 仍然适用，但**绝不以牺牲健壮性、并发、防御、可观测、测试为代价**换取"简单"。
|
||
> 2. 你的所有思考过程和回复必须使用 **简体中文**。
|
||
|
||
## 1. 项目元数据 (Metadata)
|
||
- **核心目标**: 在层次化视频树上构建可自我进化的搜索 Agent + 可训练的递归检索器（RecursiveRetriever），通过 Harness Engineering（工具、技能、记忆、中间件）的持续改进实现长视频理解；服务于科研产出。详见 `research-wiki/ARCHITECTURE.md`、`README.md`。
|
||
- **项目类型**: 科研工程混合体 + 生产级（非 MVP）
|
||
- **目标会议**: AAAI 2026（2026年6月25日）
|
||
- **后端架构**: Python 3.11（Clean Architecture 四层分层，详见 `research-wiki/ARCHITECTURE.md §2`）
|
||
- **版本管理**: Git
|
||
- **Conda 环境**: `Video-Tree-TRM` (Python 3.11)
|
||
|
||
## 1.5 系统设计类比 (Design Analogy)
|
||
|
||
本系统的自进化循环对标 PyTorch 训练循环：
|
||
|
||
| PyTorch 概念 | 本项目对应 | 代码位置 |
|
||
|-------------|-----------|----------|
|
||
| `DataLoader` | 出题 question_gen | `app/question_gen/generator.py` |
|
||
| `model.forward()` | 推理 inference | `app/harness/inference.py` + `core/agent/loop.py` |
|
||
| `loss.backward()` | 诊断 diagnose | `core/evolution/diagnose.py` |
|
||
| `optimizer.step()` | 进化 evolve | `core/evolution/evolve.py` |
|
||
| `nn.Parameter` | Skills + Prompts（版本化） | `store/skills/`, `store/prompts/` |
|
||
| `training loop` | 外层循环 runner | `app/harness/runner.py` |
|
||
| `checkpoint` | Store 版本快照 | `app/harness/workspace.py` |
|
||
| `grad clipping` | 进化 validation | `core/evolution/validate.py` |
|
||
|
||
### 关键推论
|
||
|
||
- **只有 inference 是 agent-controlled**（LLM 自主决定工具调用），其余三步均为 code-controlled workflow。
|
||
- 四步之间通过**函数调用 + 明确返回类型**组合，无需调度框架。
|
||
- Store 中版本化资源 = 可回滚的"模型权重"，Workspace = 一次"训练实验"。
|
||
|
||
## 2. 常用命令 (Commands)
|
||
|
||
### 2.1 Conda 环境管理
|
||
|
||
> [!CRITICAL]
|
||
> **所有 Python 相关命令（pytest / ruff / 脚本）必须在 `Video-Tree-TRM` 环境中执行**
|
||
> - 使用 `conda activate Video-Tree-TRM & <command>` 确保命令在正确环境中运行
|
||
> - 或在命令前显式添加 `source activate Video-Tree-TRM &&`
|
||
> - 如果需要使用 LLM 可以依据 `.env` 环境变量文件使用
|
||
> - 对于需要长时间运行的程序请尽量使用tmux，并且不要进行任何形式的日志缓存，确保所有日志可以立刻马上输出，这有助于帮助我们检查错误。
|
||
|
||
```bash
|
||
# 激活项目环境（交互式 shell）
|
||
conda activate Video-Tree-TRM
|
||
|
||
# 推荐：使用 conda run 执行命令（自动使用正确环境）
|
||
conda activate Video-Tree-TRM & pip install xxx
|
||
conda activate Video-Tree-TRM & pytest xxx
|
||
conda activate Video-Tree-TRM & python xxx
|
||
```
|
||
|
||
### 2.2 Makefile 入口
|
||
|
||
常用工程动作统一收口到 `Makefile`。
|
||
|
||
```bash
|
||
make test # conda 环境内跑 pytest + 覆盖率
|
||
make lint # ruff check --fix + ruff format（app/ core/）
|
||
```
|
||
|
||
### 2.3 代码质量检查
|
||
```bash
|
||
# 代码格式化
|
||
conda activate Video-Tree-TRM & ruff format app/ core/ adapters/
|
||
|
||
# 代码检查并自动修复
|
||
conda activate Video-Tree-TRM & ruff check app/ core/ adapters/ --fix
|
||
```
|
||
|
||
### 2.4 GPU 约定
|
||
|
||
> [!CRITICAL]
|
||
> - **本地 (RTX 4070 Ti SUPER)**：默认 `CUDA_VISIBLE_DEVICES=0`
|
||
> - 所有涉及 GPU 的命令都要显式 `CUDA_VISIBLE_DEVICES=<idx>` 前缀，避免占用他人卡
|
||
> - **严禁**省略 `CUDA_VISIBLE_DEVICES` 导致 PyTorch 自动选卡
|
||
|
||
### 2.5 实验入口（sh 文件）
|
||
|
||
每个 sh 文件是自包含的实验记录，写死全部参数，零参数即可复现（GPU 卡号除外）。
|
||
|
||
```bash
|
||
# 典型调用
|
||
CUDA_VISIBLE_DEVICES=0 bash scripts/<experiment>.sh
|
||
MODE=mock N_SAMPLES=10 bash scripts/<experiment>.sh # smoke test
|
||
```
|
||
|
||
## 3. 标准作业程序 (Standard Operating Procedure)
|
||
> **Agent 必须严格遵守以下生命周期执行任务（全量强制，不分级、不因任务"简单"而省略）：**
|
||
|
||
### Phase 1: 规划与设计 (Planning)
|
||
1. **需求探索**: 涉及创建新功能、新组件、修改行为时，**必须**先调用 `brainstorming` skill 进行需求探索与设计。无论用户的指令多么具体、改动多么简单，都不得跳过此步骤（除非用户显式说"跳过 brainstorming"）。
|
||
2. **查阅规格 & 讨论**: 仔细阅读 `research-wiki/`（单一事实源）下对应的文档，了解项目最新情况。对于不理解的地方请与人类进行多轮讨论，确保理解人类的设计意图。
|
||
3. **日志方案设计**: 功能会产生运行时数据时，**必须**调用 `structured-logging` skill 设计日志方案。
|
||
4. **撰写计划**: 正式编码前，**必须**调用 `writing-plans` skill 撰写实现计划。
|
||
5. **审核门控（差异化）**:
|
||
- **design：Claude 自审 → Codex 审 → 人类审**（保留人类门，批准后方可进入计划阶段）。
|
||
- **plan：Claude 自审 → Codex 审 → 直接执行**（无 plan 人类门）；plan 经 Claude 自审 + Codex 审通过后直接进入 Phase 2 执行。
|
||
|
||
### Phase 2: 执行与验证 (Execution & Verification)
|
||
1. **编码**: 审核通过后，开始编写代码。
|
||
2. **验证**: 声称工作完成前，**必须**调用 `verification-before-completion` skill 进行验证。
|
||
- **环境检查**: 确保所有命令在 `Video-Tree-TRM` 环境中执行。
|
||
- *失败*: 回到编码阶段修复，直到通过。
|
||
- *成功*: 进入下一步。
|
||
|
||
## 4. 核心规则 (Rules)
|
||
|
||
### 4.1 核心原则 (Core Principles)
|
||
|
||
> 以下原则按优先级排序，冲突时高优先级原则优先。
|
||
|
||
#### P1: YAGNI（You Aren't Gonna Need It）
|
||
- 不写当前用不到的代码。"未来可能需要"不是写代码的理由。
|
||
- 但 YAGNI **不等于**砍健壮性：生产级所需的并发控制、防御校验、可观测埋点、错误隔离与测试**都是"当前需要"**，不在 YAGNI 削减之列。
|
||
- 抽象只在真正易变 / 需替换 / 需造测试替身的接缝处引入（见 `research-wiki/ARCHITECTURE.md §3`），其余写直白的领域函数。
|
||
|
||
#### P2: 高可读性（Readability）
|
||
- 命名：用领域术语命名，不用技术实现命名。名字应让人无需读函数体就能猜出它干什么。
|
||
- 注释：解释"为什么"，不解释"是什么"。需要注释来解释代码在做什么 = 代码不够清晰。
|
||
|
||
#### P3: 单一职责（Single Responsibility）
|
||
- 每个函数只做一件事，每个模块只负责一个领域。
|
||
- 判断标准：能否用一句话描述职责？需要用"和"连接 = 应该拆分。
|
||
|
||
#### P4: 显式优于隐式（Explicit over Implicit）
|
||
- 所有公共函数的参数和返回值必须有完整类型注解。
|
||
- 函数需要的东西通过参数传入（依赖注入），不从全局状态或环境变量中偷偷拿取。
|
||
- **严禁**使用默认参数掩盖逻辑（必须显式传递关键参数）。
|
||
|
||
#### P5: 防御性与安全性（Defensiveness & Safety）
|
||
- 所有外部输入（用户输入、API 响应、LLM 返回、文件读取）校验后再使用。
|
||
- **严禁** `except Exception: pass`。每个 except 处理特定异常类型。
|
||
- **严禁**出错后使用默认值掩盖错误。正确做法是直接报错。
|
||
- 敏感信息（API key、密码、token）不得出现在代码中，走 `.env` / 密钥管理。
|
||
|
||
#### P6: 可测试性（Testability）
|
||
- 纯函数优先：相同输入永远产生相同输出。
|
||
- 外部依赖通过端口（Protocol）注入，便于测试时替换成假实现（见 `research-wiki/ARCHITECTURE.md §3` 接缝清单）。
|
||
- 测试用例应尽可能使用真实样本，而非完全虚假的数据。
|
||
|
||
### 4.2 代码开发规范 (Code Style)
|
||
- **文档**: 所有模块、类、方法必须包含 **中文 Docstring** (功能、参数、返回值、关键实现细节)。
|
||
- **运行时检查**: 关键维度、设备一致性、门控条件必须通过 assertion 或 if 验证。
|
||
- **代码组织**:
|
||
- 使用阶段化注释 (`# Phase 1`, `# Phase 2`) 组织复杂逻辑。
|
||
- 接口返回值需包含完整诊断信息（输出、统计、溯源），使用条件标志控制。
|
||
- **命名与依赖**:
|
||
- 类名 `PascalCase`，变量描述性命名，私有变量前缀 `_`。
|
||
- 导入顺序：标准库 → 第三方库 → 项目内部。
|
||
- **日志与错误处理**:
|
||
- 使用 **loguru** 作为统一日志框架，禁用 `print()`。
|
||
- Agent 遥测走 `TelemetryRecorder` Protocol（见 §4.8），不要自己拼裸 SQL 或临时落盘。
|
||
- **功能修改**:
|
||
- **必须** 不考虑向后兼容，直接修改原文件。代码简洁性优先。
|
||
|
||
### 4.3 Git 工作流规范
|
||
- **Feature Branch**: 所有开发工作在 feature 分支上进行，**严禁**直接在 main/master 上修改。
|
||
- **增量提交**: 频繁提交，每个提交有明确的语义。
|
||
- **提交前检查**: 提交前 `git diff` 审查变更，避免提交调试代码或临时文件。
|
||
- **风险操作前备份**: 执行重构或大改动前，先提交当前状态作为回滚点。
|
||
- **Commit 规范**: 提交代码时**必须**调用 `commit` skill。
|
||
|
||
### 4.4 工作区与实现规范
|
||
- **临时文件清理**: 任务完成后删除所有临时脚本、调试输出、中间文件。
|
||
- **实现完整性**: 开始实现就必须完成到可运行状态，**严禁**留下 `TODO`、`NotImplementedError`、mock 占位。
|
||
- **知识输出路径**: 所有 Skill 产出的知识统一写入 `research-wiki/`（单一事实源）。
|
||
- 设计文档 → `research-wiki/designs/`
|
||
- 实现计划 → `research-wiki/plans/`
|
||
- 调试发现 → `research-wiki/findings/`
|
||
- 架构决策 → `research-wiki/adrs/`
|
||
- 审查记录 → `research-wiki/reviews/`
|
||
|
||
### 4.5 配置管理规范（双模式）
|
||
|
||
本项目存在两类配置，**互不混用**：
|
||
|
||
| 模式 | 用途 | 载体 | 优先级 |
|
||
|------|------|------|--------|
|
||
| **工程配置** | 系统运行所需、少变或敏感（API 密钥、Redis URL、LLM 超时等） | `pydantic-settings` + `.env`（敏感项不提交，模板见 `.env.example`） | `.env` 环境变量 |
|
||
| **科研实验配置** | 会在实验中被反复扫动 / 对比的参数（gate 阈值、batch 大小、评估口径等） | per-experiment YAML + harness run 运行快照（保证可复现） | 实验 YAML |
|
||
|
||
> **D7 配置归属判定规则（防串台，强制遵守）**：
|
||
> 某参数**是否会在科研实验中被反复扫动 / 对比**？
|
||
> - **是** → 科研配置（per-experiment YAML + harness run 快照）。
|
||
> - **否**（系统运行所需、少变、或敏感）→ 工程配置（`pydantic-settings` + `.env`）。
|
||
>
|
||
> **CLI args 仅用于单次临时覆盖，不作为任何配置的常驻来源。**
|
||
> **配置合并优先级**: CLI args > `.env` > YAML，三者统一归口到 dataclass。
|
||
|
||
- **原则**: 上述两类载体之外，严禁在代码中散落硬编码默认值；缺失关键配置应直接报错而非兜底。
|
||
- **Prompt 分类**: 推理 prompt（`system.md`、`*_extract.md`、`*_verify.md`）存放在 `store/prompts/` 下，参与版本化进化。诊断 prompt（`diagnose_*.md`）存放在项目根 `prompts/` 下，不参与版本化——它们是评估标尺，不应随进化改变。
|
||
|
||
### 4.6 测试组织规范
|
||
#### 测试哲学
|
||
- **真实场景优先**: 测试用例应使用真实数据或真实数据的二次构造，而非完全虚假的样本。
|
||
- **边缘场景处理**: 边缘场景不通过测试解决，而是通过代码中的 assertion/报错解决。测试只负责确保核心功能和核心场景能真实跑通。
|
||
- **测试目标**: 验证系统在真实条件下的端到端正确性。生产级业务应**逐步提高覆盖率并以 integration 测试为重**。
|
||
|
||
- **目录**: `tests/{unit,integration,e2e}/test_*.py`，最低覆盖率 80%
|
||
- **运行**: `conda activate Video-Tree-TRM & pytest tests/ --cov=app --cov=core --cov-report=term-missing`
|
||
|
||
#### Agent 测试输出规范（仅限 agent / LLM 类测试）
|
||
|
||
> 下述规范**只适用于涉及 agent / LLM 执行的测试**；常规单元 / 集成测试无需产出该 MD。
|
||
|
||
| 要素 | 规范 |
|
||
|------|------|
|
||
| **输出位置** | `tests/outputs/<test_module>/<test_name>_<timestamp>.md` |
|
||
| **触发时机** | 所有涉及 Agent / LLM 执行的测试 |
|
||
| **内容要求** | 任务描述、每步 Agent 输入/输出/推理过程、工具调用、最终结果 |
|
||
| **格式要求** | 结构化 Markdown（标题、代码块、列表），人类可读 |
|
||
| **分析方式** | Claude Code 读取 MD 文件，评估推理质量、任务完成度、代码正确性 |
|
||
|
||
**pytest 集成**: 使用 fixture 或工具类自动保存，测试结束后输出文件路径。
|
||
|
||
### 4.7 核心算法保真
|
||
|
||
迁移时逐一比对参考代码，不可简化。完整清单见 `research-wiki/ARCHITECTURE.md §6`（建树 4 项 + 训练 9 项 = 13 项）。
|
||
|
||
| # | 算法 | 核心逻辑 |
|
||
|---|------|---------|
|
||
| 1 | L2 轴心建树策略 | L2 先行→L3 向下→L1 向上，asyncio 链式并发 |
|
||
| 2 | VLM 批量帧描述 + JSON fallback | `_L3_BATCH_SIZE=5` 批量调用，解析失败逐帧 fallback |
|
||
| 3 | 断点续跑机制 | `progress.json` + L1 中间 JSON，按段恢复 |
|
||
| 4 | RecursiveRetriever | Cross-Attention 选择器 + ACT halt + z 状态累积 |
|
||
| 5 | CE-Gate e-process | 截断 Beta 混合、四出口门控 |
|
||
| 6 | 信息阶梯 | 冷启动 2:1、gamma-EMA、反泄漏 |
|
||
| 7 | 块顺序验证 | 基线缓存、INFRA 护栏、配对翻转 |
|
||
| 8 | 诊断瀑布 | 错误归因级联、缺陷 vs 失误、D1-D5 |
|
||
| 9 | 进化 patch 引擎 | 保护跨度、rank-and-clip、附录/动量 |
|
||
| 10 | Mini-batch 构建 | FFD + round-robin + 正确率混合 |
|
||
| 11 | Agent Loop | Thinking+JSON、json_repair、pluggy hook |
|
||
| 12 | 树环境语义搜索 | 分块 embedding、祖先去重、锚定验证 |
|
||
| 13 | 训练循环编排 | 三级嵌套、慢更新10步、断点续训 |
|
||
|
||
> **任何 PR 涉及上述算法的修改，必须在 commit message 中标注对应序号并说明变更理由。**
|
||
|
||
### 4.8 Agent 遥测
|
||
|
||
每次 LLM/VLM 调用必须经过 `TelemetryRecorder` Protocol（`core/evolution/protocols.py`）记录。完整规范见 `research-wiki/ARCHITECTURE.md §4`。
|
||
|
||
| 必录字段 | 类型 | 说明 |
|
||
|----------|------|------|
|
||
| `call_id` | str | UUID，本次调用唯一标识 |
|
||
| `parent_call_id` | str? | 父调用 ID（agent step → LLM call 链路） |
|
||
| `session_id` | str | epoch/step/question 关联 ID |
|
||
| `model_name` | str | 使用的模型名 |
|
||
| `provider` | str | API 端点标识 |
|
||
| `messages` | str (JSON) | 原始输入 |
|
||
| `response` | str | 原始输出 |
|
||
| `prompt_tokens` / `completion_tokens` | int | token 用量 |
|
||
| `latency_ms` | int | 延迟毫秒 |
|
||
| `cache_hit` | bool | 是否命中 Redis 缓存 |
|
||
| `error` | str? | 异常信息（正常为 null） |
|
||
|
||
**存储实现**：`adapters/telemetry.py` → SQLite `telemetry.db`。`GovernedLLMClient`（`adapters/llm.py`）在每次调用后自动写入，**严禁**绕过此路径裸调 LLM API。
|
||
|
||
### 4.9 LLM 韧性
|
||
|
||
所有 LLM/VLM 调用必须经过 `GovernedLLMClient`（`adapters/llm.py`）治理，禁止裸调 OpenAI SDK。治理栈五层（详见 `research-wiki/ARCHITECTURE.md §5`）：
|
||
|
||
| 层 | 机制 | 说明 |
|
||
|---|------|------|
|
||
| 1 | 硬超时 | `asyncio.wait_for(call, timeout=config.llm_timeout)` |
|
||
| 2 | 指数退避重试 | `max_retries`、`base_delay`、`max_delay`（可配置） |
|
||
| 3 | 熔断器 | 连续 N 失败 → 短路 M 秒 → 探针恢复 |
|
||
| 4 | Redis 响应缓存 | content-addressed：`hash(model + messages)` → response |
|
||
| 5 | ARQ 任务队列 | 长时间推理任务异步执行 |
|
||
|
||
> 熔断参数（`LLM_CIRCUIT_BREAKER_THRESHOLD`、`LLM_CIRCUIT_BREAKER_COOLDOWN`）和超时（`LLM_TIMEOUT`）通过 `.env` 工程配置管理。
|
||
|
||
## 5. 项目结构规范
|
||
|
||
目录结构遵循 `research-wiki/ARCHITECTURE.md §2.3` Clean Architecture 四层分层：
|
||
|
||
```text
|
||
project_root/
|
||
├── CLAUDE.md # Agent 指令入口
|
||
├── README.md # 项目概览与快速开始
|
||
├── Makefile # 工程命令收口（test / lint）
|
||
├── main.py # CLI 入口（唯一允许的根目录 .py）
|
||
├── .env / .env.example # 工程配置（.env 不提交 Git）
|
||
├── .claude/ # Claude 配置（skills, hooks, tools）
|
||
│
|
||
├── core/ # 可提取内核（不依赖 app/、adapters/）
|
||
│ ├── agent/ # AgentLoop 引擎（loop, types, protocols）
|
||
│ ├── evolution/ # 诊断+进化引擎（diagnose, evolve, gate）
|
||
│ └── types.py # 跨模块共享类型
|
||
│
|
||
├── app/ # 应用层（组合 core + adapters，领域特化）
|
||
│ ├── tree/ # 建树模块（TreeIndex, VideoTreeBuilder）
|
||
│ ├── harness/ # 训练 harness（runner, inference, batching）
|
||
│ ├── question_gen/ # 新题构建
|
||
│ ├── search/ # 搜索 Agent 装配（prompt, skills）
|
||
│ ├── retriever/ # 可训练检索器（RecursiveRetriever）
|
||
│ └── ports.py # 应用层端口
|
||
│
|
||
├── adapters/ # 外部实现层（LLM/VLM/embedding/cache/遥测）
|
||
├── config/ # 声明性配置（YAML，禁止 .py）
|
||
├── store/ # 版本化资源（skills/prompts/questions/videos）
|
||
├── workspaces/ # 实验工作区
|
||
├── prompts/ # 诊断 prompt（不参与进化，是评估标尺）
|
||
├── scripts/ # 实验运行脚本（仅 .sh，禁止 .py）
|
||
├── tools/ # 独立工具脚本（不被其他模块 import）
|
||
├── tests/ # 测试代码
|
||
│ ├── unit/
|
||
│ ├── integration/
|
||
│ └── e2e/
|
||
├── data/ # 数据（不提交 Git）
|
||
├── logs/ # 运行日志（不提交 Git）
|
||
├── results/ # 实验结果输出
|
||
└── research-wiki/ # 研究知识库 = 单一事实源
|
||
```
|
||
|
||
### 硬性规则
|
||
1. **依赖只能向内**：`adapters/` → `app/ports.py` / `core/protocols.py`；`app/` → `core/`；`core/` 绝不依赖 `app/` 或 `adapters/`。
|
||
2. **可提取内核判据**：`core/agent/` 和 `core/evolution/` 搬到没有 adapters 的环境，用假实现替换 Protocol 即可原样运行。
|
||
3. **根目录除 `main.py` 外不得出现 `.py` 文件。**
|
||
4. **`prompts/`、`config/` 只放声明性文件**（.md / .yaml / .json），不放可执行代码。
|
||
5. **`scripts/` 只放 `.sh` 脚本**，不放 `.py` 文件。
|
||
6. **禁止创建以下目录名**：`helpers/`、`common/`、`shared/`、`misc/`、`lib/`。必须使用具体的领域名称。
|
||
7. **`data/`、`logs/` 不提交 Git。**
|
||
|
||
## 6. 上下文获取与迷途指南 (Context & Navigation)
|
||
|
||
| 需求 | 文档路径 | 说明 |
|
||
|------|----------|------|
|
||
| 系统架构与边界 | `research-wiki/ARCHITECTURE.md` | 四层分层、依赖方向、接缝清单、核心算法、韧性规范 |
|
||
| 项目目标与背景 | `README.md` | 核心业务逻辑与项目定性 |
|
||
| 关键决策记忆 | `research-wiki/adrs/` | 架构决策记录（ADR） |
|
||
| 领域知识压缩摘要 | `research-wiki/query_pack.md` | idea-creator 的核心上下文输入 |
|
||
| 研究知识库索引 | `research-wiki/index.md` | 所有实体的分类索引 |
|
||
| 代码结构检索 | `graphify-out/GRAPH_REPORT.md` + `conda activate Video-Tree-TRM & graphify query/path/explain/affected`（主对话可用 `/graphify`） | 读代码前先查图谱而非盲读；首次需手动 `/graphify .`，刷新用 `/graphify . --update` |
|
||
|
||
## 7. 输出规范
|
||
|
||
### 7.1 语言要求
|
||
- 所有输出语言: **中文**
|
||
|
||
### 7.2 文档撰写约束
|
||
|
||
#### 优先使用的表达方式（按优先级排序）
|
||
1. **表格** — 对比、配置、参数说明、实验结果等结构化信息
|
||
2. **伪代码** — 描述算法和流程时，而非完整可执行代码
|
||
3. **Mermaid 流程图** — 流程、架构、状态转换
|
||
4. **简洁的连贯段落** — 论述逻辑关系时，2-3 句话的短段落
|
||
|
||
#### 严格禁止
|
||
- **禁止大段代码**: 文档中不得出现超过 15 行的代码块。需要展示实现思路时用伪代码；需要完整代码时引用文件路径。
|
||
- **禁止碎片化列点**: 不得出现连续超过 5 个的短句列点。改用表格或合并为连贯段落。
|
||
- **禁止冗长解释**: 能用一句话说清的不用三句话。能用表格呈现的不用段落罗列。
|
||
|
||
#### 文档长度控制
|
||
|
||
| 文档类型 | 长度上限 | 超出时的处理 |
|
||
|---------|---------|------------|
|
||
| 实验报告 | 300 行 | 拆分为摘要 + 附录，摘要不超过 100 行 |
|
||
| 计划/方案（`research-wiki/plans/`） | 1000 行 | 聚焦关键决策，细节留给代码注释 |
|
||
| 设计文档（`research-wiki/designs/`） | 400 行 | 用 Mermaid 图替代文字描述 |
|
||
| 会议/进度记录 | 100 行 | 只记结论和 action items |
|
||
|
||
## 8. Skill 使用规则
|
||
|
||
> [!CRITICAL]
|
||
> **Skill 调用是无条件义务，不是判断题。**
|
||
>
|
||
> 当任务匹配下方触发时机表中的任一条件时，你**必须**在行动前通过 Skill 工具调用对应 Skill。
|
||
>
|
||
> **以下任何理由都不构成跳过 Skill 的正当依据：**
|
||
> - "用户已经给出了明确方案，brainstorming 不会产生额外价值"
|
||
> - "这个改动很小/很简单，不需要走完整流程"
|
||
> - "我判断调用后也会发现不适用"
|
||
> - "用户的指令已经足够具体，不需要探索"
|
||
>
|
||
> **你没有权限做这个判断。** 即使你 100% 确信 Skill 不会改变结果，仍然必须调用。
|
||
> 调用后 Skill 流程明确指示"不适用"时，才可以跳过后续步骤。
|
||
>
|
||
> **优先级（从高到低）：**
|
||
> 1. 用户的显式指令（如用户说"跳过 brainstorming"则可跳过）
|
||
> 2. Skill 的详细流程（优先于 CLAUDE.md 中的宏观规则）
|
||
> 3. CLAUDE.md 宏观规则
|
||
|
||
### 工程类 Skill（当前主力，按触发时机强制调用）
|
||
|
||
| Skill | 触发时机 |
|
||
|-------|---------|
|
||
| `brainstorming` | 创建新功能、新组件、修改行为前 |
|
||
| `writing-plans` | 有需求/规格后、编码前 |
|
||
| `systematic-debugging` | 遇到 bug、测试失败、异常行为时 |
|
||
| `test-driven-development` | 实现功能或修复 bug 时 |
|
||
| `verification-before-completion` | 声称完成、提交、创建 PR 前 |
|
||
| `commit` | 提交代码时 |
|
||
| `finishing-a-development-branch` | 实现完成且测试通过，准备集成时 |
|
||
| `subagent-driven-development` | 执行实现计划时：Claude 子代理实现 + 3×Codex 审（规格合规 / 功能质量 / 代码风格） |
|
||
| `requesting-code-review` | 完成重要功能、合并前（Codex 审查） |
|
||
| `receiving-code-review` | 收到代码审查反馈后 |
|
||
| `structured-logging` | 功能会产生运行时数据时，brainstorming 之后 |
|
||
| `research-wiki` | 管理知识库、初始化、查询、统计时 |
|
||
| `harness-eval` | 功能完成后评估性能，或 subagent-driven-development Step 10 |
|
||
|
||
### 科研类 Skill（现阶段先不用，不写门控规则）
|
||
|
||
> 这些 skill 为一等公民资产，但项目当前处于工程为主的架构平台期，**现阶段先不用**；**何时启用由模型依据任务实际需要自行判断**，不设强制触发门控。
|
||
|
||
| Skill | 用途 |
|
||
|-------|------|
|
||
| `research-lit` | 了解领域现状、找论文、文献综述 |
|
||
| `idea-creator` | 生成 / 排序研究想法 |
|
||
| `novelty-check` | 验证想法新颖性、查新 |
|
||
|
||
## 9. Research Wiki
|
||
|
||
> 项目唯一知识仓库（单一事实源），所有 Skill 产出的研究与开发知识统一存储于此。
|
||
|
||
### 初始化
|
||
使用 `/research-wiki init` 或 `python3 .claude/tools/research_wiki.py init research-wiki/`。
|
||
|
||
### 实体类型
|
||
|
||
| 实体 | 目录 | 来源 Skill |
|
||
|------|------|-----------|
|
||
| paper | `papers/` | research-lit |
|
||
| idea | `ideas/` | idea-creator |
|
||
| experiment | `experiments/` | run-experiment（未来） |
|
||
| claim | `claims/` | novelty-check |
|
||
| gap | `gaps/` | research-lit, idea-creator |
|
||
| design | `designs/` | brainstorming |
|
||
| finding | `findings/` | systematic-debugging, verification |
|
||
| adr | `adrs/` | 架构决策记录（重大不可逆的技术决策） |
|
||
| plan | `plans/` | writing-plans |
|
||
| review | `reviews/` | code-review |
|
||
| schema | `schemas/` | structured-logging |
|
||
| metric | `metrics/` | structured-logging, harness-eval |
|
||
|
||
### 关键文件
|
||
|
||
| 文件 | 说明 |
|
||
|------|------|
|
||
| `query_pack.md` | 压缩摘要（≤8000 字符），idea-creator 的核心上下文 |
|
||
| `index.md` | 自动生成的分类索引 |
|
||
| `log.md` | 所有变更的审计日志 |
|
||
| `graph/edges.json` | 实体间关系图（NetworkX JSON） |
|