迭代研究專案 (Iterate Research Project)
使用這項技能,讓一個研究專案在變動中保持誠實。核心習慣是:分類工作、寫入到最狹窄的持久化位置、記錄證據,然後僅同步協作者需要的摘要和看板。
有兩條規則貫穿一切:
- Markdown 優先,看板其次。 先更新來源 Markdown 或
_ai筆記。之後才同步PROJECT_BOARD.html。 - 看板是地圖,不是日誌。
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)
- 從
_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,然後提交變更的安全檔案並附上明確路徑。
上下文壓縮與交接衛生 (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。