Community写作与编辑github.com

迭代研究项目技能

用于研究组合和迭代项目工作流的Codex技能

迭代研究项目技能 是什么?

本技能旨在围绕一个研究项目建立一套可复用的迭代工作流,其核心习惯包括:对工作内容进行分类、写入最窄的持久化位置、记录证据,然后仅同步协作所需的摘要和看板。该技能遵循两条核心规则:一是优先更新Markdown或`_ai`笔记,再同步`PROJECT_BOARD.html`;二是将看板视为当前状态的映射和导航工具,而非原始日志。技能强调“新想法即新子项目”的迭代习惯,通过为每个新尝试创建独立的日期命名的子项目目录来保持历史可追溯和可比较,从而避免覆盖或无限重做单一尝试。该技能既可独立应用于单个项目,也可作为可选集成与组合管理技能配合使用,支持主线路、暂存和归档三种子项目状态,并提供了详细的分类、上下文压缩、同步级别、数据管理和文献管理的指导。

兼容平台~Claude Code✓Codex CLI~Cursor
npx skills add jiangjin1999/codex-research-project-skills

Installed? Explore more 写作与编辑 skills: steipete/notion, langchain-ai/langchain, bytedance/podcast-generation · View all 6 →

在你喜欢的 AI 中提问

打开一个已预加载此 Agent Skill 的新对话。

文档

迭代研究项目

使用此技能来保持一个研究项目在变化中保持诚实。核心习惯是:对工作进行分类,写入最窄的持久化位置,记录证据,然后仅同步协作所需的摘要和看板。

贯穿始终的两条规则:

  1. Markdown优先,看板其次。 首先更新源Markdown或_ai笔记。然后才同步PROJECT_BOARD.html。
  2. 看板是地图,不是日志。 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。

迭代循环

  1. 从_ai/project_overview.md、_ai/project_board_spec.md、_ai/task_plan.md、_ai/findings.md、_ai/progress.md和相关文件夹README恢复上下文。
  2. 在编辑项目文件之前确认操作者的Git身份;如果缺失,请用户自行配置并暂停。
  3. 用一句话命名当前迭代:问题、尝试或决策。
  4. 首先创建或更新最窄的源文件。
  5. 将改变方向的发现记录在_ai/findings.md中;将操作、验证和失败的路径记录在_ai/progress.md中。
  6. 当阶段、阻碍或下一个操作发生变化时,更新_ai/task_plan.md。
  7. 在上下文压缩之前、完成一个小步骤之后或在切换主题/子项目之前,在最匹配的Markdown文件中编写一个紧凑的交接说明。
  8. 应用同步级别来决定是否修改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。

相关技能