規格與 tasks 準備好後，就可以進入 apply。Speclink 在這裡仍然沿用 Spectra 的基本作法：AI 讀取 tasks.md、逐項處理工作，完成後再把 checkbox 打勾。

不過，實際用起來，還有兩件事需要處理：有些工作需要我親自完成，不能全交給 AI；而 AI 完成的工作，除了打勾，我也希望能留下當時改過哪些檔案的紀錄。

不是每一個 task 都能交給 AI

大部分的 tasks 可以交給 AI，例如修改 code、補上測試或執行 command。但有些工作需要我的帳號權限，或需要我親自確認結果，像是到第三方後台建立 API key、在外部環境完成設定，或實際操作產品、確認畫面是否符合預期。這些步驟也需要記在 tasks 裡，才不會做到一半才發現還有事情沒處理。

所以，我在 Speclink 的 tasks.md 裡加入了 [M]，用來標記需要使用者手動完成的 task：

## 1. 完成匯入功能

- [x] 1.4 補上匯入失敗時的錯誤處理
- [ ] [M] 1.5 實際匯入一份文件並確認內容正確

## 2. 串接後續操作

- [ ] 2.1 加入匯入完成後的編輯入口

[M] 的靈感： 【Day - 12】介紹過 Spectra 用 [P] 標記可能可以一起做的 tasks。我也沿用在 task 前面加標記的方式，用 [M] 表示這項工作需要使用者手動完成。

propose 產生 tasks 時，AI 會依照需求判斷哪些工作需要使用者完成。我也可以直接提醒它，例如「登入第三方後台、建立 API key，再放進本機環境」這一步要由我處理，就請它標成 [M]。如果 AI 漏掉了，也可以在進入 apply 前請它補上，先把每項工作該由誰完成寫清楚。

像上面的範例，AI 完成 code 與測試後，還需要我實際匯入文件、確認結果。等 1.5 完成，下一組的 2.1 就可以繼續交回 AI。這類確認工作通常放在一組 tasks 的最後，但手動 task 要放在哪裡，還是得看其他工作是否需要先等它完成。

例如，後面的 code 必須先取得 API key 才能繼續，那麼建立 API key 的 [M] 就要放在前面。apply 遇到這種情況時會先停下來，請我們完成手動 task；如果後面的工作不受影響，AI 就可以先跳過 [M]，繼續處理其他 tasks，但不會替我們把它打勾。

在 Speclink Desktop 裡，這類 task 也會另外顯示「手動」標記，和一般交給 AI 的工作分開：

用 [M] 分開手動 task 後，我們至少知道每一個 checkbox 應該由誰完成了。可是，對 AI 可以執行的 tasks 來說，打勾仍然只表示「這項工作被標成完成」，沒有告訴我們它當時實際改了哪些檔案。

為什麼要讓 touched files 跟著 change 保存？

我很常在前一份 change 還沒有 archive 時，就先開始下一份。等回頭歸檔，工作目錄裡可能已經混進其他 change 的修改，只看當下的 Git 狀態，就不容易知道前面每項 task 做過什麼。這有一部分也是我自己的使用習慣造成的XD，所以我想先把 task 完成時留下的檔案紀錄保存下來。

【Day - 12】介紹過，Spectra 2.3.1 會在 task 完成時暫存 touched files，到了 archive 再重新查看工作目錄，把 code 與 tests 的線索寫進正式規格的 @trace。我希望 task 完成時的紀錄也能留下來，所以在 Speclink 裡，把這些檔案清單寫進 change 目錄下的 .evidence.json，歸檔時一起保存。

之後想回查某一項工作，就可以先找到對應的 task，再看它留下的檔案清單：

不過，如果不同 changes 的修改已經混在一起，記錄時仍然可能混到其他工作的檔案。這份清單可以幫忙找資料，但要知道某一處修改屬於哪份 change，還是得回頭核對。那麼，這些檔案是怎麼記下來的呢？

task done 把線索寫進 .evidence.json

Speclink 的 apply Skill 完成一項工作後，會透過 speclink task done 更新 checkbox。就在這個時候，CLI 也會查看目前 Git 工作目錄有哪些異動，排除已經被前面 tasks 記錄過的檔案，再把這次新出現的 touched files 寫進：

openspec/changes/<change-name>/.evidence.json

一筆 evidence 會包含下面這些欄位：

{
  "version": 2,
  "change": "add-sync",
  "entries": [
    {
      "taskId": "tsk_01...",
      "taskDesc": "1.1 實作同步流程",
      "actor": "Developer",
      "repo": "main",
      "headCommit": "4d8f...",
      "touchedFiles": [
        "src/sync.js",
        "src/sync.test.js"
      ],
      "recordedAt": "2026-08-29T10:00:00Z"
    }
  ]
}

除了 task 與檔案清單，Speclink 也會盡可能記下執行者、repo、當時的 HEAD commit 與時間。之後回頭查，就比較容易知道這筆紀錄是在什麼時候、哪個專案狀態下留下的。

.evidence.json 不會在進入 apply 時就先建立。只有 task done 找到尚未被前面 tasks 記錄的檔案異動，才會新增一筆紀錄。如果某項工作只整理文件狀態，或改過的檔案已經記在前面的 task 裡，這次就不會新增 evidence，但 task 還是可以正常打勾。因此，沒有 evidence 不代表 task 沒有完成。

同樣地，即使整份 change 沒有 evidence，archive 仍然可以繼續，只會提示這次沒有各項 task 的執行紀錄。有留下的 .evidence.json，則會和 proposal、specs、design 與 tasks 一起移進封存目錄。至於正式規格的 @trace 最後留下什麼，我們等走到 archive 時再一起看。

evidence 留下線索，但不是完成證明

雖然檔名叫做 evidence，這份紀錄主要讓我們回查某項 task 打勾時記下了哪些檔案，以及當時留下的執行者、repo 與 commit 資訊。它沒有記錄測試結果，也不能證明功能已經照規格完成。

同一個檔案可能被好幾項 tasks 改過，裡面也可能同時實作不同的 requirements，所以不能拿這份清單判斷某條 requirement 對應哪個檔案、哪幾行 code。想確認測試是否通過、code 品質如何，以及功能有沒有做對，還是需要測試、Review 與 Verify。

老實說，我平常也不會特別打開 .evidence.json 一筆一筆看XD，大多還是確認 tasks.md 有沒有全部打勾。這些紀錄主要是讓 Skill 與工具在 commit、archive 或後續查核時可以讀取，需要追查時也有線索可以找，不需要我每天逐筆整理。

到這裡，每項 task 完成時留下的紀錄，已經能跟著 change 一起保存。不過，如果好幾份 changes 都在同一個工作目錄裡修改，記錄時仍然可能把別份 change 的檔案一起算進來。

我後來用 Git Worktree 替它們分開工作目錄。但有些 change 得等另一份完成才能開始，光是把目錄分開，還是不能直接一起做。那麼，哪些可以先開工、哪些需要等一下，又該在哪裡實作呢？接下來，就來看看 Speclink 怎麼安排這些工作吧！

參考資料

• Spectra 2.3.1 Release
• Speclink propose Skill 正式規格
• Speclink apply Skill
• Speclink task evidence 正式規格