evidentloop/sopify

Resumable, traceable AI coding — plans, handoffs, and evidence stay with the repo across hosts.

Sopify – 可恢復、以計畫為先的 AI 編碼

是什麼 – Sopify 是一個輕量級協定層，位於現有的 AI 編碼助手（GitHub Codex、Anthropic Claude、Qoder、GitHub Copilot）之上。它在需求不清晰時會強制助手暫停，強制記錄計畫，並將該計畫與驗證證據儲存在由 Git 追蹤的隱藏 .sopify/ 資料夾中。當您（或團隊成員）稍後在任何支援的主機上開啟同一個程式庫時，只需輸入 ~go，主機將自動從下一個未完成的任務恢復保存的工作流程。

為何重要 – 許多 AI 編碼工具會直接跳轉到程式碼生成，這常常導致：

在事實未明確前就進行過早變更，
切換機器或 LLM 主機時遺失上下文，以及
設計決策未被記錄。 Sopify 透過將規劃與決策步驟轉化為專案資產，隨程式庫一同移動，解決了這些問題。

核心概念

概念	作用
受控工作流程	主機請求澄清，建立設計，將工作拆分為任務，並將計畫寫入 `.sopify/plan/`。只有在您明確確認後才會產生程式碼。
恢復指標	一個小型本機檔案（不在 Git 中）記錄您目前所處的步驟。在任何主機上輸入 `~go` 會讀取計畫，並從下一個任務繼續。
可追溯性	每個需求、設計選擇與審查均以純文字/JSON 檔案形式儲存在 `.sopify/` 中。您之後可檢視某行程式碼為何存在。
主機無關性	相同的 `.sopify/` 檔案被 Codex、Claude、Qoder 以及（有限程度上）Copilot 理解，因此團隊可自由切換助手而不會破壞流程。

快速開始（來自 README）

# 為特定主機（此處為 Codex，美國英語）安裝 Sopify 層
curl -fsSL https://github.com/evidentloop/sopify/releases/latest/download/install.sh \
  | bash -s -- --target codex:en-US

需要 Python 3.11+。

安裝後，開啟已包含 .sopify/ 資料夾的程式庫（或新建一個），執行：

~go            # 開始或恢復完整工作流程
~go plan       # 僅建立計畫，尚未產生程式碼
~go finalize   # 在交付證據準備就緒後關閉當前計畫

安裝程式可在執行前檢閱（`curl … -o install.sh && less install.sh`）。Windows 使用者有等效的 PowerShell 指令碼。

設定（範例）

# 放置於程式庫根目錄的 sopify.config.yaml
brand: auto
language: en-US
workflow:
  mode: adaptive   # strict | adaptive | minimal
  require_score: 7 # 主機自動推進前所需的最低置信度分數

設定檔與程式碼一同存放，並自身進行版本控制。

目錄結構（相關部分）

.sopify/
├─ blueprint/   # 基線設計規格、減量目標
├─ plan/        # 活躍計畫 + 驗證憑證
└─ history/     # 歸檔（完成）的計畫

其他原始碼檔案（`sopify_writer/`、`skills/` 等）實作協定，但無需終端使用者編輯。

典型工作流程

請求 – 您請求一個功能（例如：「新增快取層」）。
計畫 – Sopify 提示主機分析需求、產生設計，並將工作拆分為任務。計畫儲存在 .sopify/plan/ 下。
確認 – 您批准計畫後，主機才開始產生程式碼。
編碼 – 主機撰寫程式碼，附帶一份憑證，將每個變更回溯至原始任務。
恢復 – 如果您在功能中途停止，本機恢復指標會記住最後完成的任務。在另一台主機上開啟程式庫並輸入 ~go，將從任務 N+1 繼續。
歸檔 – 功能完成後，~go finalize 將計畫及其憑證歸檔至 .sopify/history/。

使用情境

團隊交接 – 開發者可在 Codex 中啟動功能，將程式庫交給使用 Claude 的團隊成員，後者無需重新解釋上下文即可恢復。
可審計性 – 管理員可審查 .sopify/plan/ 檔案，了解為何做出特定實作決策。
多語言專案 – 由於協定檔案與語言無關，只要主機支援目標語言，此工作流程即可用於 Python、JavaScript 等。

架構快照（如 README 所述）

協定核心 – 解釋 ~go 命令並管理恢復指標的核心邏輯。
預設工作流程 – 一組規則（分數門檻、自適應模式）決定主機何時必須請求澄清。
知識層 – 儲存計畫、設計藍圖與驗證憑證的 .sopify/ 檔案；這些檔案隨 Git 程式庫一起移動。

授權

程式碼與設定 – Apache 2.0
文件 – Creative Commons BY 4.0

總結

Sopify 不取代 LLM；它新增了一個有紀律、由 Git 跟蹤的流程，強制規劃、保留決策，並讓任何支援的 AI 編碼主機都能從上一次會話結束處精確接續。對於依賴 AI 助手但需要可重現性與審計追蹤的團隊，Sopify 提供了一種低開銷、主機無關的解決方案。