文件撰寫專家 (docs)

docs

寫出真人想讀的文件。要短、要白話、要圍繞著想完成某件事的人來寫。

「記錄功能 X」不是任務。「幫助某人用 X 完成 Y」才是。

分兩個階段進行。先規劃故事：誰會讀這個、他們想要什麼、應該分成幾頁。然後再寫。

規劃內容不是私密的。使用者必須看到讀者列表，並且在撰寫任何頁面前必須選擇語氣。

找文件
  → 讀取鄰近頁面
  → 第一階段：讀者 + 頁面
  → 角色閘門（在對話中寫出讀者列表，然後停止）
  → 語氣閘門（在對話中寫出語氣，然後停止）   [撰寫頁面時]
  → 載入 simple-english + i-have-adhd   [撰寫頁面時]
  → 第二階段：撰寫

功能規劃中的文件影響清單仍需通過角色閘門。但在實際撰寫頁面前，不會通過語氣閘門或載入寫作技能。

何時執行

文件與程式碼一起發布。在三個時間點執行此技能，不只是在被要求時。

• 有人要求寫文件。寫出來。
• 在規劃儲存庫中的功能或變更時。在規劃完成前，列出哪些文件是新的、哪些需要更新。這個文件影響清單是規劃的一部分，與程式碼變更同等重要。為每個頁面指定讀者。
• 完成實作時。在宣布工作完成前，撰寫或更新這些文件。一個行為的變更如果沒有隨附文件變更，就不能算完成。

最終頁面所需的技能

simple-english 和 i-have-adhd 是必要條件。它們適用於文件頁面，而非此規劃對話。

在即將撰寫頁面內容前，立即載入兩者。如果此工作框架有「技能 (Skill)」工具，請使用它。如果沒有，請從本地技能目錄讀取每個技能的 SKILL.md。不要僅憑記憶撰寫頁面。

如果缺少任一技能，請停止並告知使用者。請勿在沒有它們的情況下撰寫頁面。

它們如何組合：

• 此技能負責頁面的目標讀者、頁面劃分、問題優先於解決方案、展示而非告知、無歷史遺漏、禁用字元以及鄰近頁面結構。
• simple-english 負責句子。使用務實模式。在宣稱頁面完成前執行其自我檢查。
• i-have-adhd 負責頁面形狀：下一步行動優先、編號步驟、列表最多五項（拆分「必須」與「稍後」，或拆分頁面）、無前言、在結尾處有可見的勝利。

當從此技能載入 i-have-adhd 時，僅對頁面應用它。不要將對話的其餘部分切換為 ADHD 模式。i-have-adhd 的持續性部分在此不適用。

先找文件

在寫任何東西之前，先找出文件存放的位置。

1. 尋找 docs 資料夾。先檢查 docs/，然後是 documentation/、content/docs/、site/、website/docs/。
2. 沒找到？詢問使用者文件應該放在哪裡。不要猜測，也不要憑感覺建立資料夾。
3. 開啟新內容位置附近的 2 到 3 個現有頁面。閱讀它們的文案、結構、frontmatter 欄位和元件。記下明顯的語氣，作為語氣閘門的候選。但先不要採用。
4. 注意網站已經使用了哪些元件（步驟、分頁、提示框、卡片、折疊面板、程式碼群組等等）。不同的網站有不同的元件。
5. 重複使用這些元件來講述故事。如果網站有步驟元件，就用它來做教學。如果有分頁元件，就用它們來呈現不同框架的變體。如果網站沒有任何元件，就使用純 Markdown。永遠不要發明網站沒有的元件。

如果要寫的頁面沒有類似的範例，就找最接近的一個來閱讀並與之匹配。

「匹配鄰近頁面」涵蓋的範圍，以及不涵蓋的

匹配鄰近頁面是關於文案、結構、frontmatter 和元件：標題是否為句子大小寫、一個區段需要多少前置說明、哪些元件承載教學、如何引入程式碼範例、frontmatter 欄位是什麼。

它不能取代語氣閘門。鄰近頁面可以建議一個預設值。但它們不能為使用者回答。

它不能許可複製鄰近頁面的壞習慣。無論周圍的頁面怎麼做，禁用中的每一項以及此技能中的每一條規則，仍然適用於你撰寫的內容。一個充滿破折號的現有頁面，並不能讓你多寫一個破折號。

所以：永遠不要因為「其他頁面都這麼做」，就違反此技能陳述的規則。如果現有頁面違反了某條規則，而你認為整個頁面集合應該保持一致，那是另一個需要向使用者提出的清理事項，而不是透過默默匹配違規行為來解決。

第一階段：規劃故事

在撰寫任何內容之前執行此操作。

1. 列出誰會讀這個，以及每個人想要什麼。例如：在 React SPA 上建置的人、在伺服器端渲染應用程式中工作的人、只想要快速示範的人、正在擴展內部功能的人。不要只停留在第一個讀者。
2. 為每個讀者寫一個使用者故事：「作為一個 X，我想要 Y，以便我能 Z。」
3. 將故事轉化為頁面。一個旅程就是一個頁面。不同的旅程是不同的頁面。一個具有三個真實旅程的功能，應該有三個頁面加上一個簡短的概覽，而不是一個巨大的頁面。
4. 檢查每個讀者是否都有一條路徑。沒有頁面的讀者是規劃中的漏洞。為他們新增一個頁面或路線。

頁面劃分來自這個步驟。不要跳過它。

閘門：顯示角色

提問工具（AskQuestion、ask_user_question 及類似形式）不會在使用者閱讀的對話中顯示其有效內容。一個僅呼叫其中一個工具的回合失敗此閘門。使用者被要求確認一個他們看不到的列表。

在第 4 步之後，撰寫一條正常的對話訊息。即使也同時呼叫了提問工具，訊息正文也是必需的。訊息包含：

1. 每個讀者，作為其自己的、使用者可以掃視的簡短區塊：
   • 讀者的名稱。
   • 一個使用者故事：「作為一個 X，我想要 Y，以便我能 Z。」
   • 你將為他們撰寫的頁面。
2. 一個問題，寫在同一條訊息中：確認、刪除一個讀者或新增一個。

提問工具是可選的。僅在該列表已經在對話訊息中之後才呼叫它。該工具僅詢問簡短的選擇（確認、刪除或新增）。不要將讀者名稱、故事或頁面放在工具內部。如果該工具將是該回合的唯一輸出，則不要呼叫它。改為撰寫訊息。

然後選擇一條路徑：

預設：停止。 此訊息是整個回合。結束回合。不要寫入檔案。不要開始第二階段。不要說你將繼續，除非他們反對。

跳過等待：在同一回合繼續。 僅在以下情況之一為真時使用此路徑：

• 此對話已有使用者對該角色列表的確認。
• 使用者說了「使用合理的預設值」、「直接寫」或「不要問問題」。仍然在這一回合顯示列表，然後繼續。
• 變更是一個微小的文案編輯：錯字、損壞的連結、程式碼區塊語言或事實修正。沒有新頁面、沒有新章節、沒有重寫旅程。

在此路徑上，不要結束回合。在你顯示列表之後（或者對於微小的文案編輯，不顯示列表），繼續下一步。

以下情況不是跳過：

• 「讀者很明顯。」
• 「使用者要求文件，所以他們不希望被提問。」
• 「我已經在規劃中命名了他們。」
• 「只有一個讀者。」
• 「這是實作功能的一部分，繼續吧。」
• 「提問工具會向他們顯示列表。」它不會。列表放在對話中。

撰寫文件就是這個閘門存在的原因。它不是跳過它的理由。

少即是多：拆分，不要塞滿

不要把數千個單詞塞進一個頁面。長頁面會隱藏答案。

當一個主題有多個面向時，為每個面向建立自己的短頁面並連結它們。讀者會先看到概覽，然後點擊進入他們確切需要的內容。

範例：一個關於工具中斷的功能：

不好：一個頁面
  interrupts.md   （概覽 + 簡單案例 + 多個中斷 + 自訂，全部塞在一起）

好：一組連結的小頁面
  interrupts/index.md            它是什麼、何時使用、連結出去
  interrupts/basic.md            一個中斷，從頭到尾
  interrupts/multiple.md         流程中的數個中斷
  interrupts/custom.md           建立你自己的

每個頁面都很短且只做一件事。概覽將它們串成一個故事。

閘門：詢問語氣

此閘門位於第一階段和第二階段之間。在撰寫任何頁面前執行它。不要將其嵌套在第二階段內部。

鄰近頁面可以建議一個預設值。但它們不能為使用者回答。

撰寫一條正常的對話訊息。即使也同時呼叫了提問工具，訊息正文也是必需的。訊息包含：

1. 你從鄰近頁面推斷出的語氣，用一行說明（正式程度、需要多少前置說明、是否使用第二人稱）。
2. 一個問題，寫在同一條訊息中：使用那種語氣、更隨意、更正式，或使用者指定另一種。

提問工具是可選的，並且在該行已經在對話中之後才出現。該工具僅詢問簡短的選擇。不要僅將推斷的語氣放在工具內部。一個僅呼叫工具的回合失敗此閘門。

然後選擇一條路徑：

預設：停止。 此訊息是整個回合。結束回合。不要撰寫頁面內容。

跳過等待：在同一回合繼續。 僅在以下情況之一為真時使用此路徑：

• 此對話已有使用者的語氣選擇，包括明確的「匹配現有頁面」。
• 使用者說了「使用合理的預設值」、「直接寫」或「不要問問題」。仍然用一行說明陳述推斷的語氣，然後繼續。
• 微小的文案編輯，與角色閘門相同的例外情況。

在此路徑上，不要結束回合。在你陳述語氣之後（或者對於微小的文案編輯，不提出問題），繼續到第二階段。

以下情況不是跳過：

• 「我可以從鄰近頁面看出來。」
• 「該網站已經有風格。」
• 「對於參考頁面，語氣不重要。」
• 「我會匹配鄰近頁面並稍後提及。」

第二階段：像人一樣寫作

在角色閘門通過、語氣閘門通過，並且 simple-english 和 i-have-adhd 都已載入之前，不要撰寫頁面內容。

語氣閘門是上面的標題。先執行那個閘門。然後載入兩個技能。然後再寫。

可讀性是目標，高於一切。

• 保持易於消化。不要有文字牆，不要有大段落。將想法分解成小塊。給出完成任務所需的最少資訊量。
• 句子遵循 simple-english（務實模式）。不要內嵌一個較弱的替代品。
• 保持 Markdown 輕量。列表很好。每行都用粗體標題則不好。讓文字來承載頁面。
• 偏好純 ASCII 和普通鍵盤字元，而不是花俏的字形。像真人打字那樣寫。
• 第二人稱，行動優先。從讀者現在擁有什麼以及他們最終會擁有什麼開始。不要用「在本指南中，我們將探索...」這樣的開頭。直接開始。
• 使用 i-have-adhd 塑造頁面：第一行是讀者可以做的事情，多步驟的工作使用編號，超過五項的列表要拆分，頁面以可看見的勝利結束。

以問題開頭，然後解決它

每個頁面都以讀者來訪時遇到的問題開頭，用他們自己的話來說，在任何 API 之前。說出他們卡住的情境。然後用一兩句話說明該功能如何解決它。只有在這之後，才進入技術細節和程式碼。

先看到問題的讀者可以在幾秒鐘內知道他們是否來對了頁面。而先看到 API 簽名的讀者則必須逆向工程它到底是幹什麼用的。

如何做的第一行是下一步行動（來自 i-have-adhd）。但問題仍然先出現，以便他們知道自己來對了頁面。

不好：
  呼叫 useInterrupts() 並傳入一個解析器。該解析器在交易中為每個待處理項目執行一次...

好：
  有些工具呼叫不應該在沒有真人同意的情況下執行：轉移資金、刪除資料。中斷會暫停執行以等待該決定，然後從中斷處繼續。以下是將工具置於審批後的門控方法：

  [程式碼]

指南的順序是：問題、一行修復、然後是如何做（步驟、程式碼片段、API）。將問題限制在兩三句話，不要寫成背景論文。程式碼展示了如何解決，所以不要先用散文敘述解決方案。

展示，不要告知

不要用四段話來解釋一句話和一個程式碼區塊就能展示的內容。讀者理解 diff 或程式碼片段比理解散文更快。

不好：
  三段話描述 config 物件如何接受 middleware 陣列、每個插槽的作用以及順序如何運作。

好：
  將你的 middleware 新增到 `middleware` 陣列。順序從上到下執行：

  const app = createApp({
    middleware: [auth, logging],
  })

一個好的可執行範例勝過一頁的描述。每個程式碼範例在複製後都必須能執行，而不需要想像力來填補空白。

凡是列表都列出來

一旦一句話涵蓋了多個項目、選項、儲存、標誌或步驟，它就變成了一個列表。不要用逗號和分號將它們串成一個段落。掃視項目符號列表的讀者可以在下一秒找到他們的項目。而在段落中，他們必須閱讀整段才能發現它不適用於他們。

徵兆是：一個句子命名了兩個或更多事物，並對每個事物說了一些話。將其拆分成每個事物一個項目符號，每個項目符號一兩句話。

不好：
  每個儲存都是獨立的。只提供你需要的。對於聊天：`messages` 用於對話紀錄，`runs` 用於執行生命週期，`interrupts` 用於持久化審批（需要 `runs`），`metadata` 用於帶命名空間的鍵/值狀態。對於生成：`generationRuns` 用於執行生命週期，加上 `artifacts` 和 `blobs` 來保存生成的位元組。

好：
  每個儲存都是獨立的，所以只提供你需要的。

  對於聊天：

  - `messages`：對話紀錄。
  - `runs`：執行生命週期。
  - `interrupts`：持久化審批。需要 `runs`。
  - `metadata`：帶命名空間的鍵/值狀態。

  對於生成：

  - `generationRuns`：執行生命週期。
  - `artifacts`：保存生成的成品。
  - `blobs`：保存生成的位元組。

範本

對一個只需要一個功能的讀者顯示一個指引，對需要所有功能的讀者顯示參考資料。永遠不要混用它們或散佈它們。

Quickstart
  problem → first code run
  five lines of setup  [如果可能，使用可執行的 CodePen 等]
  <- 到 「Guides」 和 「Reference」 的連結
  <- 到下一條更深入指南的連結

Guides
  problem → one-line fix → how (steps, code, API)
  always show-don't-tell
  <- 到下一條指南和 Reference 的連結

Reference
  what is it
  API signature
  options  [作為表格或列表]
  examples  [可執行]
  related

禁用

• 沒有歷史遺漏。 一個頁面不知道讀者是從哪裡來的。「正如我們之前討論的」是對它假定已經知道的事情的人的耳語。該讀者不在那個頁面上。從現在開始解釋。
• 沒有花俏的字元。 不要使用箭頭（→）、彎引號（“ ”）、破折號（—、–）、版權符號（©）、商標符號（™、®）、項目符號（• 只在極少數情況下可以，但僅在 Markdown 的 * 和 - 無法使用時，這幾乎從未發生過）、水平省略號（…）、不間斷空格、或任何在普通鍵盤上不易輸入的字元。使用 >、->、=>、>=，而不是它們的花俏版本。
• 沒有自我介紹。 頁面不以它們自己是誰或它們涵蓋什麼來開頭。它們以讀者的問題開頭。
• 沒有序言。 不要使用「歡迎來到」、「在本指南中」、「首先呢」、「正如你所知」。直接切入主題。
• 沒有多餘的連詞。 刪除「值得注意的是」、「重要的是」、「請注意」、「有趣的是」、「順便說一句」。如果它不重要，就不要寫。
• 不要解釋程式碼。 一個好的變數名稱和一個註解勝過一段說明程式碼的段落。寫出程式碼做了什麼的散文，表明散文是重複的。刪除它。
• 不要轉述 API。 讓簽名自己說話。解釋概念，而不是語法。
• 沒有詼諧、俏皮話或文化典故。 讀者可能不分享你的文化。他們正在尋找答案，而不是娛樂。清晰和尊重比機智更好。
• 沒有多餘的形容詞。 「極其強大」、「令人難以置信的快速」、「非常簡單」——這些是填充物。展示它是什麼，並讓讀者自行判斷。
• 沒有不必要的限定詞。 「基本上」、「本質上」、「某種程度上」、「幾乎」——刪除它們。句子要麼成立，要麼不成立。
• 沒有「請」。 說明或範例在命令式語氣下是一致的。「創建一個檔案」。「運行此命令」。「這樣做」。「不要那樣做」。
• 不使用英文單位與中文數字混用。 「第 1 步」（1 為阿拉伯數字）是可以的，但全文應保持一致。文件整體應保持一致的語言風格。

文件影響清單

在規劃一個功能時，在規劃完成前，列出哪些文件是新的，哪些需要更新。此清單是規劃的一部分。

每個條目命名一個頁面，並指定誰會閱讀它。

文件影響：
- docs/tool-interrupts/overview.md   讀者：新使用者，想要了解功能
- docs/tool-interrupts/basic.md      讀者：新使用者，想為一個工具設定中斷
- docs/tool-interrupts/multiple.md   讀者：中級使用者，想要協調多個中斷

一個不命名讀者的文件影響清單是無效的。沒有名稱，就沒有通過角色閘門的記錄，頁面結構也未經審查。

帶有文件影響的跳過閘門：角色閘門

當你處於一個功能規劃中，並且列出了文件影響時，該清單的路徑是不同的。

角色閘門在此處仍然執行，但範圍更窄：你顯示文字，記錄已命名了哪些讀者，但你不會為了每個頁面分別詢問。文件規劃中需要的讀者在對話中是可見的。

你跳過的是：不需要為此處列出的頁面撰寫新的使用者故事。頁面劃分已經在文件影響清單中。不需要停止。繼續進行功能規劃。

語氣閘門在實際撰寫頁面時運行，而不是在規劃時。這意味著語氣閘門可能與功能規劃不在同一個對話中。

你仍然顯示角色閘門。在規劃對話中直接寫出讀者列表。然後繼續。不要呼叫提問工具來顯示它。

對於規劃過程中的文件影響，此技能的第二階段現在不運行。撰寫頁面是單獨的工作。

初始化

第一次執行此技能時，儲存以下預設值。

預設語氣

tone: casual

預設首選項

do_not_ask_for_tone: false do_not_ask_for_personas: false

使用者可以稍後更改這些。

技能元資料

• 名稱：docs
• 描述：寫出真人想讀的文件。
• 版本：1.0.0
• 作者：AlemTuzlak