Community寫作與編輯github.com

jiangjin1999/codex-research-project-skills

用於研究作品集與迭代式專案工作流程的 Codex 技能

codex-research-project-skills 是什麼?

這項技能旨在幫助研究專案在迭代過程中保持清晰與可追溯性。其核心方法是先對工作內容進行分類,然後將資訊寫入最精確的持久化位置,記錄實驗證據,最後僅同步協作者需要的摘要與看板。設計哲學是「純文字優先,看板其次」,並將每個新想法都建立成獨立的子專案,以確保歷史記錄是僅供附加且可比較的。該技能支援獨立運作於單一專案,也可選擇性地整合進更大的研究作品集中,透過「manage-research-portfolio」技能同步狀態至作品集儀表板。它定義了完整的專案結構、文件分類規則、看板生成規範與迭代循環,適合需要嚴格管理實驗記錄與決策過程的研發團隊或個人研究者。

相容平台~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 的新對話。

說明文件

迭代研究專案 (Iterate Research Project)

使用這項技能,讓一個研究專案在變動中保持誠實。核心習慣是:分類工作、寫入到最狹窄的持久化位置、記錄證據,然後僅同步協作者需要的摘要和看板。

有兩條規則貫穿一切:

  1. Markdown 優先,看板其次。 先更新來源 Markdown 或 _ai 筆記。之後才同步 PROJECT_BOARD.html。
  2. 看板是地圖,不是日誌。 PROJECT_BOARD.html 顯示當前狀態並指向證據。它從不儲存原始日誌、私有資料或絕對路徑。

還有一個驅動迭代的習慣:新想法 → 新的子專案。 實驗嘗試是工作的核心。當有值得嘗試的事情時,建立一個全新的 0-Project/<date>_<slug>/ 並在那裡進行迭代,而不是覆寫或無止盡地反覆迭代同一個嘗試。保持子專案小而專一;不要害怕重複。這使得歷史記錄僅供附加且可比較(請參閱 references/project-iteration-system.md)。

子專案也有不同「車道」:

  • 主線 (Mainline) — 定義當前路徑的進行中嘗試。
  • 暫存 (Parked) — 因為研究思考並非完全線性而提早捕捉的未來嘗試想法,但尚未執行。預設筆記:0-Project/_parking-lot.md。
  • 封存 (Archived) — 被放棄或取代的嘗試,並附有停止原因和證據。預設資料夾: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 Contract)

除非專案已有等效名稱,否則使用此結構。它是可複製的 _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          單一固定的 Docs 條目 + 主題索引
├── 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/ 內(該資料夾僅用於具體嘗試)。

寫入前先分類 (Classify Before Writing)

當使用者提供新材料時,選擇一個落腳點,然後決定看板是否需要變更。

使用者意圖落腳點可能觸及的看板視圖
「這是討論 / 方法 / 決策 / 比較」1-Docs/<date>_<topic>.md + 更新 1-Docs/README.md文檔地圖 (Docs Map)
「這是具體的實驗 / 嘗試」0-Project/<date>_<slug>/;將嘗試相關筆記放入其 docs/任務 (Tasks)
「這是關於某個現有嘗試的筆記」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材料 (Materials)
「這是論文 / 外部來源 / 證據」3-Paper_Survey/README.md + 證據矩陣參考文獻 (References)
「這是一個可重複使用的工作流程 / 提示 / AI 規則」4-Skills/PROJECT_SKILLS.md(通常無)
「這改變了狀態 / 下一步行動 / 阻礙」_ai/project_overview.md、_ai/task_plan.md頂層概覽 + 進度 (Progress)

如果分類改變了專案範圍、評估標準、資料邊界、公開程度,或某個嘗試是否屬於該專案,請在將其視為已確認之前先提問。對於低風險的命名/格式化,選擇保守的選項,並將假設記錄在 _ai/progress.md 中。

看板 (The Board)

PROJECT_BOARD.html 是單一專案看板。它一目瞭然地回答:這是什麼專案、當前狀態如何、什麼變更了、證據在哪裡,以及從何處繼續。它與資料夾協調一致 — 每個視圖由特定資料夾或 _ai 檔案提供資料。

基本元素:

  • 首頁 / 返回連結(持久存在):位於頁面最前方、左上角品牌區域的連結。在作品集內,使其成為指向網站根目錄 / 的 返回儀表板 連結;獨立運作時,可省略該連結或將其指向專案自身的 README.md。在建立、複製、發佈或更新頁面時,保留您選擇的任何設定。

  • 版本狀態: 頁面版本 YYYY-MM-DD-vN 和上次同步標記(可選的新鮮度/重新整理控制項)。

  • 頂層概覽(始終可見,輕量):專案名稱、一句話描述、狀態、擁有者、最近同步、當前焦點,以及至多一行簡短的進度。來源:_ai/project_overview.md。請勿在此放置階段列表、版本卡片、嘗試列表或長期路線。

  • 五個互斥的視圖,每個對應一個資料夾:

    視圖資料來源顯示內容
    進度 (Progress)_ai/progress.md、_ai/findings.md、1-Docs/README.md僅限專案級別的重大變更:目標、範圍、階段、關鍵輸出、判斷、公開狀態、簡潔版本摘要
    文檔地圖 (Docs Map)1-Docs/README.md + 根目錄結構文檔主題索引 + VS Code 資源管理器風格的結構樹(根目錄第一級文件/資料夾,以及透過 <details>/<summary> 顯示的第二級),僅限公開安全的名稱
    任務 (Tasks)0-Project/<attempt>/首先是主線嘗試;暫存的未來嘗試和已封存/棄用的嘗試僅出現在單獨的摺疊車道中
    材料 (Materials)2-Data/DATA.md資料區塊、公開性、版本、品質、使用邊界
    參考文獻 (References)3-Paper_Survey/README.md論文、方法來源、證據狀態、影響;僅在有內容時顯示

看板規則:請勿發明擁有者、狀態、優先級或未來階段;請勿添加獨立的「下一步」視圖(下一步行動位於頂層概覽、_ai/task_plan.md 或某個嘗試中);對嘗試和結構樹使用摺疊的 <details>;保持其為一個安靜的研究工作台,而非登陸頁面。未來的想法和已放棄的嘗試不得在視覺上與活躍路徑競爭。生成規則存在於 _ai/project_board_spec.md。有關完整合約,請參閱 references/project-board.md。

迭代循環 (Iteration Loop)

  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,然後提交變更的安全檔案並附上明確路徑。

上下文壓縮與交接衛生 (Context Compression And Handoff Hygiene)

在對話變得難以承載之前主動記錄上下文。當上下文視窗變大、一個小步驟完成、一個子專案達到決策點,或下一步行動將切換到另一個主題、專案或嘗試時,執行此操作。

選擇最狹窄的歸處:

情境交接位置
專案級別的討論、決策或方法筆記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(如果存在作品集)

最小的交接欄位:當前目標、已完成步驟、關鍵決策、證據路徑、未解決問題、下一步行動,以及是否需要同步看板。保持簡潔;請勿貼上完整的轉錄稿或原始日誌。

同步等級 (Sync Scale)

在編輯看板之前,根據此等級判斷每一次變更。

等級觸發條件更新內容
0唯讀探索,無新決策無
1輕微發現、小的失敗分支、臨時筆記僅 Markdown 或 _ai
2新的產物/路徑/品質控制結果、阻礙、下一步行動、狀態、文檔地圖、結構樹、資料邊界、參考文獻或嘗試發生變更來源 Markdown 或 _ai,接著同步 PROJECT_BOARD.html
3階段、里程碑、公開聲明、擁有者、優先級或公開狀態發生變更來源 Markdown、看板、PROJECT_GUIDELINES.md,以及 — 僅當專案屬於某個作品集時 — 作品集儀表板

上下文交接筆記通常為 Level 1。僅當它們改變了下一步行動、狀態、阻礙、文檔地圖、資料邊界、參考文獻狀態或嘗試狀態時,才將其提升至 Level 2。

請勿在每次編輯時都同步看板。僅在協作者需要新狀態時進行同步。

子專案記錄 (Subproject Records)

每個 0-Project/<date>_<slug>/README.md 應回答:該嘗試測試什麼問題;它使用了哪些輸入、論文、資料筆記或假設;運行了什麼或推理了什麼(目標、假設、輸入、命令、指標);什麼失敗了、改變了或變得穩定;結論和下一步行動;以及它是否影響專案狀態、資料筆記、文獻筆記或看板。將嘗試相關的討論、步驟交接和設計筆記放入該嘗試的 docs/ 資料夾。

記錄失敗的嘗試。一個帶有明確原因的失敗路徑是寶貴的專案資產。如果它被放棄或取代,請將其標記為已封存,並附帶停止原因、任何替代方案、最後證據以及不應重複的事項;僅在其達到穩定階段或決策點時,才在看板上將其顯示為一個次要的摺疊項目。

資料與文獻 (Data And Literature)

  • 使用 2-Data/DATA.md 來記錄來源、出處、版本、存取類別、允許位置、模式、品質控制和衍生製品邊界。將專案衍生的資料(特徵、軌跡、分析就緒表格、品質控制中間產物)保留在此專案的 2-Data/ 下,而非全域資料區域。切勿將原始的敏感記錄、帶有身份資訊的範例、憑證或未發佈的摘錄寫入筆記、看板或公開副本中。
  • 使用 3-Paper_Survey/README.md 來記錄可能改變方法、評估、範圍或解釋的證據。按問題、方法、資料或基準、結果、限制以及對本專案的意義來總結論文。當多個來源影響同一主張時,使用證據矩陣。優先使用簡潔的釋義和連結,而非長引用。

參考資料 (References)

  • 在建立專案結構、入口檔案、子專案、工作記憶檔案或同步規則時,請閱讀 references/project-iteration-system.md。
  • 在建立、審查或同步 PROJECT_BOARD.html 時,請閱讀 references/project-board.md。
  • 在處理資料筆記、基準來源、文獻摘要或從證據到決策的更新之前,請閱讀 references/data-and-literature.md。

相關技能