1. 项目概述：为AI研究项目构建一个“会思考”的文档大脑
如果你正在用Claude Code、Cursor这类AI编程助手来推进一个长期、复杂的AI研究项目，你肯定经历过这种痛苦：每次想让AI帮你写个训练脚本、处理一批数据，都得先花上几分钟，把项目的背景、数据在哪、之前的脚本叫啥、输出该放哪里，像挤牙膏一样一条条贴进对话里。真正的指令可能就一句话，但为了让它“理解上下文”，你得先写一篇小作文。更糟的是，几天或几周后，当你想回顾“run-7”和“run-9”到底有什么区别时，连你自己都得翻半天聊天记录，更别提让AI记住了。
Agentic Research Wiki就是为了根治这个痛点而生的。它不是一个简单的文档模板，而是一套完整的、面向智能体（Agent）的项目上下文管理系统。其核心思想是：为你的每一个AI研究项目，建立一个结构化的、可被AI智能体理解和操作的Markdown维基知识库，并配上一份专门的“导航说明书”（CLAUDE.md或AGENTS.md）。从此，你的AI助手不再是每次对话都“失忆”的新手，而是一个真正了解项目全貌、拥有持久记忆的资深协作者。
想象一下，你只需要对AI说：“把st3数据处理好生成gop格式，用8块GPU并行跑训练，创建对应的启动脚本、文档和记录。” AI就能自动理解：st3是什么数据集？gop是什么处理格式？之前的启动脚本在哪？新文档该存到哪个目录？这一切，都因为它已经通过维基库，掌握了项目的“记忆”。
这个项目的价值在于，它将项目知识从你个人的大脑和杂乱的笔记中，转移到了一个结构化的、可被机器读取的共享“外脑”中。这不仅极大提升了与AI协作的效率，也让项目本身的管理、传承和复盘变得异常清晰。
2. 核心设计理念：为什么传统的单文件规则不够用？
很多开发者习惯为项目写一个CLAUDE.md或.cursorrules文件，把所有规则都塞进去。对于小项目，这确实够用。但当一个AI研究项目运行数月，涉及数据处理、多轮训练、复杂评估和大量实验分支时，单文件规则会迅速崩溃。这背后是三个根本性的设计缺陷：
2.1 上下文爆炸与信息过载
一个成熟的研究项目，其上下文信息量是巨大的：数据集的来源与预处理流程、模型架构的多次迭代、超参数搜索记录、评估指标与对比实验、大量中途放弃或并行的实验轨道（Experimental Tracks）、相关的文献调研笔记……试图把所有信息都塞进一个文件，首先会超出大多数AI模型的上下文窗口限制。即使能塞下，当AI处理一个具体的“训练任务”时，它也不应该被无关的“数据清洗细节”或“陈旧的实验记录”干扰。这就像让你在查字典时，必须通读整本百科全书一样低效。
Agentic Wiki的解决方案：采用按需读取（Progressive Disclosure）的维基结构。Overview.md是唯一的入口，它像一本书的目录，只提供最高层级的导航。当AI需要处理数据任务时，它通过链接[[DataOverview]]进入数据分区，获取相关细节；处理训练任务时，则进入[[TrainingOverview]]。AI只在需要时，才加载特定部分的上下文，避免了信息过载。
2.2 缺乏动态写入与记忆循环
传统的规则文件是静态的、只读的。它告诉AI“应该怎么做”，但无法记录AI“做过了什么”。当AI完成一次训练，产生了新的检查点（checkpoint）和日志，这些结果去了哪里？下次再让AI基于这次训练进行评估时，你又得手动告诉它新检查点的路径。项目状态是动态变化的，但规则文件本身无法随之更新，导致AI的“知识”永远滞后于项目实际进展。
Agentic Wiki的解决方案：设计写入回环（Write-back Loop）。CLAUDE.md不仅告诉AI如何读取维基，更关键的是，它明确规定了AI在完成任务后，必须将结果写回到对应的文档中。例如，一次训练完成后，AI需要自动在Training/Records/目录下创建或更新一个记录文件，包含本次训练的配置、启动命令、关键日志摘要和产出路径。这样，维基库就成为了项目的动态记忆体。下次任何AI（甚至是你自己）查看时，都能获得最新、最全的项目状态。
2.3 项目资产分散与路径混乱
AI研究通常涉及多个代码仓库（数据预处理、训练、评估各一个）、分布在集群不同位置的数据集和输出目录。AI智能体默认的工作目录（cwd）是固定的，它很难理解“../../another-repo/scripts/train.py”这样的相对路径，更别提跨多个仓库进行文件操作了。你不得不频繁地在对话中切换上下文，或者用复杂的符号链接（symlink）来绕开这个问题。
Agentic Wiki的解决方案：将文档仓库作为AI的“工作基地”和导航中心。推荐的项目布局是，创建一个独立的ResearchProjectWiki/目录（即本项目的克隆），并将所有相关的代码仓库通过符号链接（symlink）引入到此维基目录下。同时，将数据集根目录、输出根目录也链接进来。这样，当你在ResearchProjectWiki/目录下启动AI时，CLAUDE.md会引导AI以Overview.md为起点，所有必要的代码、数据和配置路径都通过清晰的、定义在维基中的链接和命名规则来定位。AI无需离开这个上下文，就能访问到项目的所有部分。
3. 仓库结构深度解析与定制化指南
Agentic Research Wiki 提供的是一个高度结构化但也可灵活定制的骨架。理解每个部分的设计意图，是将其成功适配到你项目中的关键。
AgenticResearchWiki/ # 你的文档仓库根目录 ├── Overview.md # 【核心入口】项目全景图与导航中心 ├── CLAUDE.md / AGENTS.md # 【AI导航手册】AI阅读与操作本维基的规则 ├── Storyline/ # 【叙事层】项目背景、相关工作、目标（从Overview剥离的长文） ├── Data/ # 【数据分区】 │ ├── DataOverview.md # 数据总览：来源、格式、处理流程、目录结构 │ └── Records/ # 数据操作记录：每次数据处理的批次、参数、产出 ├── Training/ # 【训练分区】 │ ├── TrainingOverview.md # 训练总览：模型架构、超参数范围、启动脚本模板 │ └── Records/ # 训练记录：每次训练的配置、命令、日志摘要、检查点路径 ├── Eval/ # 【评估分区】 │ ├── EvalOverview.md # 评估总览：评估指标、数据集、对比基准 │ └── Records/ # 评估记录：每次评估的结果、分析、图表 ├── ExperimentalTracks/ # 【实验轨道】未收敛或已放弃的探索性分支 ├── ResearchNotes/ # 【研究笔记】文献阅读笔记、技术方案对比、决策依据 ├── Shared/ # 【共享资源】环境配置、集群使用、通用工具说明 ├── skills/ # 【技能包】预置的AI技能（导入笔记、文档维护） └── zh-CN/ # 【中文镜像】完整的中文维基副本（可选）3.1 核心文件：Overview.md与CLAUDE.md
Overview.md是你的项目“电梯演讲”和“总指挥部”。它必须精炼且具备高度可导航性。我建议的结构是：
- 项目简介：用3-5句话说明项目要解决什么问题、核心方法是什么、当前阶段。
- 目标与路线图：列出短期和长期目标，让AI理解任务优先级。
- 快速导航：这是最重要的部分。使用清晰的列表和
[[ ]]链接，指向各个分区的Overview文件。例如：- 处理数据：请阅读
[[DataOverview]]，记录写在Data/Records/。 - 启动训练：请阅读
[[TrainingOverview]]，模板见[[Training/scripts/train_template.py]]，记录写在Training/Records/。 - 运行评估：请阅读
[[EvalOverview]]，记录写在Eval/Records/。
- 处理数据：请阅读
- 关键约定：项目级的命名规则（如实验名
{model}-{dataset}-{date}-{run_id}）、关键路径的符号链接位置。
CLAUDE.md(或AGENTS.md)是AI的“操作手册”。它不应包含项目具体内容，而是元规则。其核心是定义：
- 入口点：“你的工作目录是本仓库根目录。开始任何任务前，请先阅读
Overview.md。” - 阅读协议：“文档中使用
[[文件名]]表示链接。遇到链接时，应优先读取该文件以获取详细信息。” - 写入协议：“完成任务后，你必须将结果总结并写入到对应分区的
Records/目录下。文件名应遵循YYYY-MM-DD-Task-Description.md格式。” - 路径解析：“本项目使用符号链接。
[[code/train]]指向实际的训练代码仓库。所有路径均相对于本仓库根目录进行解析。”
实操心得：在编写
CLAUDE.md时，要像在给一个非常守规矩但缺乏常识的新人写工作指南。指令必须绝对清晰、无歧义。可以多使用“必须”、“总是”、“禁止”等词语来规范AI的行为。
3.2 分区设计：Data/,Training/,Eval/
这三个分区是大多数AI研究项目的核心流水线，采用相同的结构：一个*Overview.md文件加一个Records/目录。
DataOverview.md：这里要定义数据的“世界观”。包括原始数据源（URL、路径）、数据格式说明、预处理流水线的每一步（清洗、标注、增强、划分）、以及处理后数据的目录树结构。最重要的是，要给出一个数据批次（Batch）的命名规范，例如processed-v1.2/，并在Records/中记录每个版本的处理逻辑和变更原因。TrainingOverview.md：这是AI编写训练脚本的蓝图。应包含：模型配置（配置文件路径、关键参数说明）、训练循环逻辑、日志和检查点的保存格式与周期、分布式训练（如多GPU）的启动方式模板。提供一个脚本模板极其重要，AI可以基于此模板快速生成新的训练任务脚本。EvalOverview.md：定义评估的“标准答案”。明确列出所有使用的评估指标及其计算方式、评估数据集及其路径、以及用于比较的基线模型结果。这样，当AI执行评估后，它就知道将结果填入哪个表格，与谁进行对比。
Records/目录是动态记忆的关键。每个记录文件都是一个独立的、原子性的任务报告。我强烈建议使用前端元数据（Front-matter）来标准化记录。例如，一个训练记录可以是：
--- task: training model: model-a dataset:># 链接代码仓库 ln -s /path/to/your/code/sr-data-pipeline ./ ln -s /path/to/your/code/sr-training ./ ln -s /path/to/your/code/sr-evaluation ./ # 链接数据和输出目录（可选，或在Overview中说明绝对路径） ln -s /data/ ./data-root ln -s /project/outputs/ ./output-root现在，你的维基仓库就成了一个包含所有项目资源的“门户”。
4.2 编写你的Overview.md
打开Overview.md，开始填充你的项目信息。记住，这是给AI的第一印象。
# 图像超分辨率项目（Super-Resolution Project）Overview ## 项目简介 本项目旨在开发基于深度学习的图像超分辨率模型，当前聚焦于4倍放大倍率。核心方法为ESRGAN的改进变体，重点优化在复杂自然场景下的纹理恢复能力。 ## 当前目标（2023年Q4） 1. 在DIV2K数据集上完成基础模型（SRModel-v1）的训练与调优。 2. 构建针对人脸图像（CelebA-HQ子集）的专项评估流程。 3. 探索引入轻量化模块，为移动端部署做准备。 ## 快速导航 **AI助手，请根据你的任务类型，首先阅读对应的总览文档：** - **数据处理任务**：请阅读 [[DataOverview]]，所有数据处理记录应写入 `Data/Records/`。 - **模型训练任务**：请阅读 [[TrainingOverview]]，训练脚本模板位于 `[[sr-training/scripts/train_template.py]]`，记录写入 `Training/Records/`。 - **模型评估任务**：请阅读 [[EvalOverview]]，评估脚本位于 `[[sr-evaluation/evaluate.py]]`，记录写入 `Eval/Records/`。 - **探索新想法**：请先在 `ExperimentalTracks/` 下创建新文档进行记录。 ## 关键路径与约定 - **代码**：`sr-data-pipeline/`, `sr-training/`, `sr-evaluation/` 已链接至本目录。 - **数据**：原始数据在 `data-root/DIV2K/`，处理后数据应在 `data-root/processed/` 下。 - **输出**：所有训练检查点、日志输出至 `output-root/`。 - **命名规则**：实验命名格式为 `{模型名}-{数据集}-{日期}-{运行号}`，例如 `SRModel-v1-DIV2K-20231027-run1`。4.3 配置CLAUDE.md以驯服你的AI助手
这是最关键的一步。你需要编辑CLAUDE.md，让它完全适应你的工作流。
# 项目维基导航与操作规则（For AI Agent） ## 首要原则 1. **你的工作目录（cwd）始终是本仓库的根目录**。所有文件路径均基于此目录。 2. **开始任何新任务前，必须首先阅读 `Overview.md`**，以理解项目背景和任务类型。 3. 本仓库使用维基链接语法 `[[文件名]]` 或 `[[目录/文件名]]`。遇到链接时，应将其视为必须读取的引用，以获取完整上下文。 ## 文档阅读协议（Progressive Disclosure） - 根据 `Overview.md` 的指引，进入对应分区的 `*Overview.md` 文件（如 `DataOverview.md`）。 - 仅加载与当前任务直接相关的文档。例如，执行训练任务时，无需加载 `EvalOverview.md` 或 `ExperimentalTracks/` 下的内容，除非明确引用。 - `Storyline/`, `ResearchNotes/`, `Shared/` 目录下的文档为参考信息，仅在需要了解背景或解决特定问题时按链接读取。 ## 文档写入与更新协议（Write-back Loop） **完成任务后，你必须更新项目文档以保持记忆。** 1. **记录文件**：在对应分区的 `Records/` 子目录下创建新的Markdown文件。 2. **命名规范**：`YYYY-MM-DD-任务简述.md`，例如 `2023-10-27-Train-SRModel-v1-on-DIV2K-run7.md`。 3. **内容格式**： - 文件开头使用YAML Front-matter记录元数据（见下方示例）。 - 正文需包含：任务执行的**完整命令**、关键的**配置参数**、**输出路径**（使用 `[[ ]]` 链接）、**简要结果摘要**以及**遇到的问题与解决方法**。 4. **更新索引**：如果创建了重要的新文件（如新的实验轨道），应考虑在相关的 `Overview.md` 或父级目录的 `README.md` 中添加指向它的链接。 ## 路径与符号链接 - 本仓库通过符号链接集成了代码与资源。`sr-training/` 指向真实的训练代码库。 - 在编写脚本或命令时，请使用基于本仓库根目录的相对路径（如 `./sr-training/train.py`）。 - 在文档中引用外部路径时，请使用 `[[ ]]` 链接到已创建的符号链接名（如 `[[output-root/SRModel-v1/...]]`）。 ## 技能（Skills） 本仓库集成了以下技能，在相关场景下自动或按指令应用： - `import-notes`: 将外部笔记归类并导入本维基。 - `project-doc-update`: 在修改文档时，确保遵守本仓库的结构与命名规则。 --- **示例：训练记录Front-matter** ```yaml --- task: training model: SRModel-v1 dataset: DIV2K date: 2023-10-27 gpus: 4 run_id: run-7 checkpoint: [[output-root/SRModel-v1/DIV2K/20231027-run7/checkpoint_epoch_200.pth]] log: [[output-root/SRModel-v1/DIV2K/20231027-run7/training.log]] ---### 4.4 与AI协作的实战流程 现在，假设你要启动一轮新的训练。打开你的AI编程助手（如Claude Code），将工作目录切换到你的维基仓库根目录。 **你只需要输入一句提示：** > “基于SRModel-v1架构，在DIV2K数据集上启动一轮4 GPU的训练，使用AdamW优化器，学习率设为1e-4，运行编号为run-8。” **AI会执行以下自动化流程：** 1. **读取导航手册**：加载 `CLAUDE.md`，知道要先看 `Overview.md`。 2. **理解任务类型**：从 `Overview.md` 中得知这是训练任务，被指引到 `TrainingOverview.md`。 3. **获取蓝图**：阅读 `TrainingOverview.md`，找到模型配置路径、脚本模板、输出目录规则和命名约定。 4. **组装并执行**：根据模板生成具体的训练脚本，填充你提供的参数（AdamW, lr=1e-4），生成正确的启动命令（如 `python -m torch.distributed.launch --nproc_per_node=4 ...`），并在后台或交互式地执行它（取决于AI工具的能力）。 5. **写入记忆**：训练任务提交或完成后，AI在 `Training/Records/` 下创建文件 `2023-10-28-Train-SRModel-v1-DIV2K-run8.md`，记录完整的命令、配置、以及输出的检查点和日志路径。 整个过程，你无需反复交代背景。AI就像一个熟悉项目的老手，自动完成了从理解意图到执行记录的全流程。 ## 5. 技能包详解与高级用法 `skills/` 目录下的两个预置技能是提升效率的利器。 ### 5.1 `import-notes`：将历史笔记资产化 我们都有这样的经历：项目初期，各种想法、命令、结果散落在记事本、聊天软件、甚至纸质便签上。这个技能就是帮你把这些碎片信息“资产化”，纳入维基管理体系。 **工作原理**：AI会读取你指定的一批笔记（一个文件夹或直接粘贴的内容），然后： 1. **分类**：根据内容判断它属于哪个分区（数据、训练、评估、研究笔记等）。 2. **提取**：提炼核心信息（日期、关键参数、结论）。 3. **归档**：在对应的 `Records/` 或 `ResearchNotes/` 目录下，创建一个格式规范的Markdown文件，并可能更新相关 `Overview.md` 的链接。 **如何使用**： - **文件夹模式**：在AI对话中，输入“请使用 `import-notes` 技能，处理文件夹 `~/my_old_notes/` 下的所有内容。” - **批量粘贴模式**：直接粘贴一大段混合的笔记内容，然后说“请导入这些笔记。” AI会先给你一个迁移计划预览，确认后执行。你可以使用“**batch mode**”参数来跳过对每个文件的确认，实现全自动导入。 > **实操心得**：在首次导入大量历史笔记前，建议先手动整理出一个最核心、最规范的笔记让AI处理，观察其分类和归档结果。这相当于对AI进行了一次“规则微调”，后续批量处理时效果会更好。 ### 5.2 `project-doc-update`：维基的“自动保洁员” 随着项目推进，文档会增多，一些实验轨道会被标记为“废弃”，文件命名可能变得不一致。这个技能定义了一套文档维护规则，AI在创建、移动或修改任何文档时，都会自动触发这些检查。 **核心规则包括**： - **命名检查**：确保 `Records/` 下的文件遵循日期前缀格式。 - **链接有效性**：检查 `[[ ]]` 链接指向的文件是否存在，如果不存在则提示。 - **过期内容归档**：将 `ExperimentalTracks/` 中标记为“已放弃”或超过一定时间未更新的文档，移动到 `ExperimentalTracks/Archive/` 子目录。 - **索引更新**：当在重要目录（如根目录或分区根目录）创建新文件时，提示是否更新 `README.md` 或 `Overview.md` 中的文件列表。 **如何使用**：这个技能通常是隐式工作的。当你对AI说“把上次失败的实验记录整理一下”或“更新评估结果文档”时，AI在操作过程中就会应用这些规则。你也可以显式触发一次全库扫描：“请运行 `project-doc-update` 技能，清理并整理所有文档。” ## 6. 常见问题与排查技巧实录 在实际使用中，你可能会遇到一些典型问题。以下是我在多个项目中实践后总结的排查清单。 | 问题现象 | 可能原因 | 解决方案 | | :--- | :--- | :--- | | AI无法理解 `[[ ]]` 链接，或找不到文件。 | 1. AI工具不支持维基链接语法。<br>2. 链接路径拼写错误或大小写不敏感。<br>3. 文件确实不存在。 | 1. 检查你的AI工具（如Cursor、VSCode插件）是否支持 `[[ ]]` 解析。如果不支持，需在 `CLAUDE.md` 中将其定义为“请将 `[[XXX]]` 视为指向 `XXX.md` 文件的引用”。<br>2. 在 `CLAUDE.md` 中强调路径准确性，并建议AI使用 `find` 或 `ls` 命令验证路径。<br>3. 确保文件已创建，或使用符号链接正确映射。 | | AI完成任务后没有写回记录，或记录格式混乱。 | 1. `CLAUDE.md` 中的写入规则不够强制或清晰。<br>2. AI的上下文在长任务中丢失，忘记了要写回。<br>3. 技能 `project-doc-update` 未正确加载或触发。 | 1. 强化 `CLAUDE.md` 中关于“必须写回”的指令，使用更绝对的措辞，并提供一个无法忽视的模板。<br>2. 对于长时任务，在任务描述结尾再次强调“完成后，请按规则在XX目录创建记录”。<br>3. 检查技能安装路径是否正确，或尝试在提示词中显式调用该技能。 | | 符号链接在AI环境中无法解析（AI报错“文件不存在”）。 | AI进程的工作环境可能对符号链接的支持或权限与你的Shell环境不同。 | 1. 在 `Overview.md` 和 `CLAUDE.md` 中，同时提供符号链接名和**真实的绝对路径**作为注释。<br>2. 考虑使用简单的文本文件（如 `PATH_REFERENCES.md`）来存储关键路径的映射关系，让AI去读取这个映射文件，而不是直接解析符号链接。 | | 维基内容越来越多，AI在 `Overview.md` 中迷失，加载了过多无关上下文。 | `Overview.md` 变得过于臃肿，包含了太多细节或链接。 | **严格遵守“按需披露”原则**：保持 `Overview.md` 极度精简，只提供最高层级的导航。将详细说明下沉到各分区的 `Overview` 文件。使用“更多细节请参阅 `[[DataOverview]]`”这样的指引，而非直接展开所有内容。定期重构 `Overview.md`，移除过时或次要的链接。 | | 多个AI助手（如同时使用Claude和Cursor）操作同一个维基，导致冲突。 | 同时写入同一个文件，或对项目状态的理解不一致。 | 1. **建立文件锁约定**：在 `CLAUDE.md` 中约定，在编辑某个 `Overview` 或关键记录文件前，先检查文件是否被其他进程锁定（可创建一个简单的 `.lock` 文件机制）。<br>2. **强化状态同步**：鼓励更频繁地写回小粒度的记录，而不是一次性写一个大报告。这样冲突的概率和影响范围会变小。<br>3. **以维基为唯一信源**：训练所有AI都严格从维基中读取最新状态，避免依赖自己对话历史中的过时记忆。 | **我个人最深刻的体会是**：这套系统的成功，**90%依赖于前期 `CLAUDE.md` 和 `Overview.md` 的设计与编写质量**。你必须像一个严谨的系统架构师一样，预先定义好所有的协议和接口。一旦这套“宪法”建立起来并得到AI的遵守，后续的协作就会变得无比顺畅。它强迫你和你的团队以更结构化、更持久化的方式思考项目，这本身就是一个巨大的价值。开始时会觉得有点繁琐，但坚持几周后，你会发现项目拥有了前所未有的清晰度和可协作性，那种“一切尽在掌握”的感觉，对于长期复杂的研究项目来说，是无价的。
