迭代研究项目
使用此技能来保持一个研究项目在变化中保持诚实。核心习惯是:对工作进行分类,写入最窄的持久化位置,记录证据,然后仅同步协作所需的摘要和看板。
贯穿始终的两条规则:
- Markdown优先,看板其次。 首先更新源Markdown或
_ai笔记。然后才同步PROJECT_BOARD.html。 - 看板是地图,不是日志。
PROJECT_BOARD.html展示当前状态并指向证据。它永远不会存储原始日志、私人数据或绝对路径。
还有一条驱动迭代的习惯:新想法 → 新子项目。 实验尝试是工作的核心。当有东西要尝试时,创建一个新的0-Project/<date>_<slug>/并在其中进行迭代,而不是覆盖或无限次地重做一次尝试。保持子项目规模小且目的单一;不要害怕重复。这使历史保持仅追加并可比较(参见references/project-iteration-system.md)。
子项目也有通道:
- 主线路 — 定义当前活动路径的尝试。
- 暂存 — 由于研究思维不完全是串行的而提前捕获的未来尝试想法,但尚未执行。默认笔记:
0-Project/_parking-lot.md。 - 已归档 — 已放弃或被取代的尝试,并保留停止原因和证据。默认文件夹:
0-Project/_archive/。
低成本暂存。一个未来的想法可以是在_ai/task_plan.md、1-Docs/或0-Project/_parking-lot.md中的一条简短条目;只有当该想法有足够的输入、标准或交接价值时,才创建一个完整的尝试文件夹。
将讨论和尝试分开路由:讨论、决策、比较和方法说明进入1-Docs/<date>_<topic>.md;带有输入、标准、输出或结果的具体试验进入0-Project/<date>_<slug>/;尝试内的局部讨论进入0-Project/<attempt>/docs/<date>_<topic>.md。
独立或位于组合内。 此技能是自包含的:它可以独立用于任何路径下的单个项目 — 无需组合。项目所需的一切(文件夹、入口文件、看板、工作记忆、Git策略)都位于项目文件夹内。可选地,当项目位于一个组合内时(<slug>-project/<project>/),使用manage-research-portfolio技能将状态、所有者、优先级和公开状态同步到组合仪表盘。当独立运行时,跳过此技能中的所有“组合仪表盘”和“注册表”步骤 — 它们是可选集成,绝不是先决条件。
项目契约
如果项目尚未有等效的名称,请使用此结构。它是可复制的_PROJECT_TEMPLATE骨架。
<project>/
├── README.md 入口:一句话目标、文件夹地图、快速开始、当前状态
├── PROJECT_GUIDELINES.md 项目本地同步规则、文件夹边界、HTML分类
├── PROJECT_BOARD.html 看板:当前状态地图和导航
├── GIT_WORKFLOW.md 此项目的Git身份 + 每次变更的提交策略
├── scripts/
│ └── init_project_git.sh 用于设置身份和首次提交的可选辅助脚本
├── 0-Project/ 具体尝试/实验(每个尝试一个0-Project/<date>_<slug>/)
├── 1-Docs/
│ └── README.md 单一的固定文档入口 + 主题索引
├── 2-Data/
│ └── DATA.md 来源、出处、权限、版本、模式、质量控制、边界
├── 3-Paper_Survey/
│ └── README.md 阅读队列、论文笔记、证据矩阵、方法来源
├── 4-Skills/
│ └── PROJECT_SKILLS.md 项目本地提示、AI规则、可重用流程
└── _ai/
├── project_overview.md 目标、范围、状态、所有者、优先级、下一步
├── project_board_spec.md 如何从源生成/同步PROJECT_BOARD.html
├── task_plan.md 当前阶段、计划、阻碍、下一步
├── findings.md 稳定的发现、未解决的问题
└── progress.md 最近有意义的同步、操作、验证、提交
根文件是入口 + 规则 + 看板 + Git策略。所有具体内容都放入最匹配的编号文件夹;切勿将材料堆积在项目根目录,也切勿将项目概述、看板规则或长期指南放入0-Project/(该文件夹仅用于具体尝试)。
在写入前分类
当用户提供新资料时,选择一个落地位置,然后决定看板是否改变。
| 用户意图 | 落地位置 | 可能影响的看板视图 |
|---|---|---|
| “这是一个讨论/方法/决策/比较” | 1-Docs/<date>_<topic>.md + 更新1-Docs/README.md | 文档地图 |
| “这是一个具体实验/尝试” | 0-Project/<date>_<slug>/;将尝试内笔记放入其docs/下 | 任务(任务尝试) |
| “这是一条关于某个现有尝试的笔记” | 0-Project/<attempt>/docs/<date>_<topic>.md | 通常是任务,如果它改变了项目级索引则可能是文档地图 |
| “这是一个未来尝试的想法” | _ai/task_plan.md、1-Docs/或0-Project/_parking-lot.md;仅当具体时才创建完整尝试文件夹 | 通常无,或一个暂存的任务通道 |
| “此尝试已放弃/被取代” | 保留尝试文件夹或将其移至0-Project/_archive/;用停止原因、证据和替代品标记为已归档 | 归档/折叠的任务通道 |
| “这是数据/基准信息” | 2-Data/DATA.md | 材料(数据材料) |
| “这是一篇论文/外部来源/证据” | 3-Paper_Survey/README.md + 证据矩阵 | 参考文献 |
| “这是一个可重用工作流/提示/AI规则” | 4-Skills/PROJECT_SKILLS.md | (通常无) |
| “这改变了状态/下一个操作/阻碍” | _ai/project_overview.md、_ai/task_plan.md | 顶部概览 + 项目进度 |
如果分类改变了项目范围、评估标准、数据边界、公开暴露或某个尝试是否属于该项目,请在将其视为已确认之前询问。对于低风险命名/格式化,选择保守选项并在_ai/progress.md中记录假设。
看板
PROJECT_BOARD.html是单项目看板。它一目了然地回答:这个项目是什么、当前状态如何、发生了什么变化、证据在哪里以及从何处继续。它与文件夹协调 — 每个视图由特定文件夹或_ai文件提供数据。
基本元素:
-
首页/返回链接(持久性):页面最前面、左上角品牌区域的一个链接。在组合内,使其指向站点根目录
/的返回仪表盘链接;独立运行时,可省略或指向项目自己的README.md。在创建、复制、发布或更新页面时保留您选择的任何内容。 -
版本状态: 页面版本
YYYY-MM-DD-vN和最后同步标记(可选的新鲜度/刷新控件)。 -
顶部概览(始终可见,浅色):项目名称、一句话描述、状态、所有者、最近同步、当前关注点以及最多一条简短进展行。来源:
_ai/project_overview.md。此处不要放置阶段列表、版本卡、尝试列表或长期路线。 -
五个互斥视图,每个映射到一个文件夹:
视图 数据来源 显示内容 项目进度 _ai/progress.md、_ai/findings.md、1-Docs/README.md仅项目级重大变更:目标、范围、阶段、关键输出、判断、公开状态、紧凑版本摘要 文档地图 1-Docs/README.md+ 根结构文档主题索引 + 类似VS Code Explorer的结构树(根级别-1文件/文件夹以及通过 <details>/<summary>的级别-2),仅公开安全名称任务(任务尝试) 0-Project/<attempt>/首先是主线路尝试;暂存的未来尝试和已归档/废弃的尝试仅在单独的折叠通道中显示 材料(数据材料) 2-Data/DATA.md数据块、公开性、版本、质量、使用边界 参考文献 3-Paper_Survey/README.md论文、方法来源、证据状态、影响力;仅在存在内容时显示
看板规则:不要发明所有者、状态、优先级或未来阶段;不要添加独立的“下一步”视图(下一步操作存在于顶部概览、_ai/task_plan.md或某个尝试中);对尝试和结构树使用折叠的<details>;保持其为安静的研究工作台,而非登陆页面。未来的想法和已放弃的尝试不得在视觉上与活动路径竞争。生成规则位于_ai/project_board_spec.md。完整契约参见references/project-board.md。
迭代循环
- 从
_ai/project_overview.md、_ai/project_board_spec.md、_ai/task_plan.md、_ai/findings.md、_ai/progress.md和相关文件夹README恢复上下文。 - 在编辑项目文件之前确认操作者的Git身份;如果缺失,请用户自行配置并暂停。
- 用一句话命名当前迭代:问题、尝试或决策。
- 首先创建或更新最窄的源文件。
- 将改变方向的发现记录在
_ai/findings.md中;将操作、验证和失败的路径记录在_ai/progress.md中。 - 当阶段、阻碍或下一个操作发生变化时,更新
_ai/task_plan.md。 - 在上下文压缩之前、完成一个小步骤之后或在切换主题/子项目之前,在最匹配的Markdown文件中编写一个紧凑的交接说明。
- 应用同步级别来决定是否修改
PROJECT_BOARD.html,然后使用显式路径提交已更改的安全文件。
上下文压缩与交接卫生
在对话变得代价高昂之前,主动将上下文记录下来。在以下情况下执行此操作:上下文窗口变得太大、一个小步骤完成、一个子项目达到决策点、或者下一个操作将切换到另一个主题、项目或尝试。
选择最窄的位置:
| 情况 | 交接位置 |
|---|---|
| 项目级讨论、决策或方法笔记 | 1-Docs/<date>_<topic>.md |
| 尝试级步骤、观察或局部讨论 | 0-Project/<attempt>/docs/<date>_<topic>.md |
| 项目状态、阻碍、下一个操作或验证摘要 | _ai/progress.md、_ai/findings.md、_ai/task_plan.md |
| 跨项目或组合上下文 | 如果存在组合,则为其<slug>-ai/<date>_<topic>.md |
最小交接字段:当前目标、已完成的步骤、关键决策、证据路径、未解决的问题、下一个操作以及是否需要同步看板。保持紧凑;不要粘贴完整的转录或原始日志。
同步级别
在编辑看板之前,根据此级别判断每次更改。
| 级别 | 触发条件 | 更新内容 |
|---|---|---|
| 0 | 只读探索,无新决策 | 无 |
| 1 | 微小发现、小失败分支、临时笔记 | 仅Markdown或_ai |
| 2 | 新工件/路径/质量控制结果、阻碍、下一个操作、状态、文档地图、结构树、数据边界、参考文献或尝试更改 | 源Markdown或_ai,然后同步PROJECT_BOARD.html |
| 3 | 阶段、里程碑、公开声明、所有者、优先级或公开状态更改 | 源Markdown、看板、PROJECT_GUIDELINES.md以及——仅当项目属于某个组合时——组合仪表盘 |
上下文交接笔记通常是级别1。仅当它们更改了下一个操作、状态、阻碍、文档地图、数据边界、参考文献状态或尝试状态时,才将其提升到级别2。
不要每次编辑都同步看板。仅在协作者需要新状态时进行同步。
子项目记录
每个0-Project/<date>_<slug>/README.md应回答:该尝试测试什么问题;它使用什么输入、论文、数据笔记或假设;运行或推理了什么(目标、假设、输入、命令、指标);什么失败了、改变了或变得稳定了;结论和下一个操作;以及它是否影响项目状态、数据笔记、文献笔记或看板。将尝试内的讨论、步骤交接和设计笔记放入该尝试的docs/文件夹。
记录失败的尝试。带有明确原因的失败路径是有用的项目资产。如果它被放弃或被取代,请将其标记为已归档,并附上停止原因、替代品(如有)、最后证据以及不要重复的内容;看板中仅在其达到稳定阶段或决策点时,将其显示为次要折叠项。
数据与文献
- 使用
2-Data/DATA.md记录出处、版本、访问类别、允许的位置、模式、质量控制和派生工件边界。将项目派生数据(特征、轨迹、分析就绪表格、质量控制中间件)保留在此项目的2-Data/下,而不是全局数据区域。切勿将原始敏感记录、带有身份标识的示例、凭据或未发布摘录写入笔记、看板或公开副本。 - 使用
3-Paper_Survey/README.md记录可能改变方法、评估、范围或解释的证据。按问题、方法、数据或基准、结果、局限性以及对此项目的意义来总结论文。当多个来源指向同一声明时,使用证据矩阵。偏爱简洁的释义和链接,而非长篇引用。
参考文献
- 创建项目结构、入口文件、子项目、工作记忆文件或同步规则时,阅读
references/project-iteration-system.md。 - 创建、审查或同步
PROJECT_BOARD.html时,阅读references/project-board.md。 - 处理数据笔记、基准出处、文献摘要或证据到决策的更新之前,阅读
references/data-and-literature.md。