robot-notes /關於/寫作慣例與 lessons learned

robot-notes 的寫作慣例與 lessons learned

這個 repo 不只是內容,也累積了一套「怎麼把技術主題寫清楚、寫可信」的工作法。這份記錄它的慣例與一路踩過的雷,讓之後擴展的人(或 agent)能延續同樣的品質,不必重踩。

每篇的工作流

1. 研究 + 查證:動筆前先查。涉及外部事實(API、標準、型號、版本、端點)用 research sub-agent + WebSearch/WebFetch 查官方來源,每個主張附 URL。
2. 第一性原理寫:先講「為什麼」「在解什麼」,再展開細節;不是直接貼設定檔。
3. 配 SVG:數學、概念、流程一律配圖。
4. 去 AI 味:寫成人話,刪掉 AI 痕跡(見下)。
5. push GitHub:小步提交,commit 訊息講清楚改了什麼、為什麼。
6. 專家 + 學生審查:派兩個 sub-agent,一個查技術正確性與出處、一個查可讀性,抓到的問題回第 2 步迭代。

一路踩過的雷(lessons)

• GitHub 的行內 $...$ 數學常常不渲染——夾在中文段落裡會漏成純文字(讀者真的看到 $F_t \le \mu N$ 這串)。改用反引號 + Unicode 符號(μ、≤、×、Σ、∫);獨立成行的 block $$ 才較穩。多行公式用 ``` code block + Unicode,最穩且與行內反引號的寫法一致。

  另外兩個同類的雷:\text{} 裡不要放中文(MathJax 的數學字型沒有 CJK 字符,會變豆腐);組合字元與冷門符號少用(p̂、⟹ 在等寬字型下可能缺字或對不齊,改寫成 p_est、→)。

• 不要只靠肉眼判斷 markdown 會不會跑版,用 GitHub 自己的 renderer 當 oracle:

  jq -Rs '{text: ., mode: "gfm"}' FILE.md > req.json
  gh api --method POST /markdown --input req.json > out.html
  

  然後比對來源與產出的元素數量(表格 <table>、圖 <img、標題 <h1-6>、code <pre>),並 grep out.html 看有沒有漏出未渲染的 $。block $$ 渲染正常時會被包成 class="js-display-math"(交給前端 MathJax);沒被包住就是不會渲染。這比事後在網頁上一頁頁看快得多。

• 驗證腳本本身也會壞,而且壞掉時看起來像「通過」。這一輪連續踩到兩次:
  • 用 gh api ... --jq '.archived and "已封存" or "活躍"' 查 repo 是不是封存,恆印 true——jq 的 and/or 回傳布林值而非運算元(跟 JavaScript 不同),所以 false or "活躍" 是 true。當時的結論剛好沒錯,但那個驗證方法什麼都證明不了。
  • 用上面那招對帳時 grep '<table>',八個檔全報 0 個表格——實際上 GitHub 輸出的是 <table role="table">,是自己的過濾器有洞,不是表格沒渲染。

  兩次的共同點:輸出「乾淨」時最危險。判準是先做一次正對照——拿一個「一定會中」的樣本餵進同一條管線,確認它真的會回非空;回不了非空就是過濾器壞了,不是被驗的東西沒問題。

• 純格式的改動,就只改格式——別順手「補完」自己沒查證的描述。踩過:把三張產品截圖從裸 ![]() 改成置中寫法時,覺得原本的 alt「Keenon 官網首頁」寫得太籠統,順手改成「Keenon DINERBOT T10 官網頁面」。圖我沒開來看過——那其實是官網首頁,主視覺是一台掃地機,整張圖沒有 T10。假宣稱就這樣夾在一個標題寫著「改排版」的 commit 裡進了 repo,審查時也沒人會特別去看排版 commit。覺得原本的描述不夠好是另一件事,要另外查證再改。

• 查證常抓出自己的記憶錯。這 repo 修正過的例子:WireGuard 其實沒有 IETF 標準軌 RFC(誤記成 RFC 9203,那是別的東西);STM32F405/F407 沒有 CRYP 硬體加速;SROS2 的 CLI 是 create_enclave 不是舊的 create_key;對 rmf_deployment_template 的佐證一度講過頭(範本其實沒那樣設)。結論:涉及具體事實一律查證,別靠記憶。

• 誠實標註勝過漂亮話:廠商效能數字標明來源(別當中立基準)、會變動的時程標日期、延遲這種依條件而定的用量級(LEO 數十 ms / GEO ≥250 ms)而非單一精確值、不確定的標「待查證」。

• 「第一性原理」是方法,不是口頭禪:有一篇一度出現 10 次「第一性原理」當標籤,讀起來就是 AI 味。精神保留(從根本推導),但把標籤稀釋成自然說法。

• 寫成人話,不要規格表簡寫:像「分鐘級 → 秒級」「又快又穩又強」這種,改成把具體情境講出來(「改一行要等好幾分鐘、結果還時好時壞」)。

• 「流程圖」不等於「概念圖」:對方要的是步驟順序(sequence),就別只給分層架構圖——兩者都有價值,但要給對。

• ASCII art 一律升級成 SVG,而且每張 SVG 都用 chrome-headless 渲染後讀圖檢查(爆框、截字、箭頭顏色不一致都靠這抓)。

• 一篇可被多視角索引:STM32 的 TLS 篇既是「韌體」也是「資安」的子篇——用連結把它組進不同主題的階層,別實體搬檔去破壞既有分類。

• 審查迭代真的會抓到東西:不只可讀性,還抓過「佐證與現行版本不符」「pseudo 跟真實 API 概念衝突」這類技術問題。每篇 push 後跑一輪值得。

• 概念圖要先找參考、再重繪,不要憑空手繪:幫廣域連線篇配「車車 + 衛星」概念圖時,一開始憑想像手畫,被退「不夠專業」。正確順序是 先蒐集參考 → 真的看過 → 再重繪:用搜尋找真實案例圖 / 官方示意圖 / 新聞配圖,把圖下載到本地實際看過,理解構圖與元素後再畫;可參考專業新聞圖重繪,或用一致的開源素材庫(如 Lucide,ISC 授權)當積木,別自己捏一堆不一致的形狀。版權上以「參考重繪 / 開源素材」為主,別把受版權的新聞圖直接放進 repo。

• 找資料中英文並重,優先在地案例:同一主題只查英文是偷懶;中文與在地(台灣)案例往往更有說服力,也更貼讀者。例:廣域連線篇補上台灣大哥大 × AST SpaceMobile 的手機直連衛星 MOU(2026-03-02 MWC)、中華電信 IoT-NTN 測試、Ericsson × CJ Logistics 私有 5G 倉儲,比純國外案例更落地。

• 把充分條件當成充要條件,是最難自己看出來的一種錯:四足步態那篇原本寫「duty factor < 0.5 必有飛行相,這是幾何必然不是經驗值」。其中 d ≥ 0.5 ⟹ 無騰空相 本身是對的——Hildebrand 研究的對稱步態裡,同一對的左右腳恰好差半個週期,所以每一對就是個 n=2 的系統,門檻正好 1/2。錯的是把箭頭反過來也當成真:d < 0.5 完全可以沒有騰空相,前對的空檔被後對填掉就行,amble(靈長類、大象)就是這樣。判斷法:寫下「⟺」「必然」「才可能」之前,把箭頭兩個方向分開各證一次。 正向證得出來會給人「整條都懂了」的錯覺,而反向往往根本沒被檢查。
  • 這條教訓自己也修過一次,而且第一版的診斷是錯的。 第一版寫成「不要把來源的『統計上偏向』升級成幾何必然」——但 0.5 對四足並不是統計說法,它確實是幾何門檻,只是充分而非必要。錯誤的診斷比沒有診斷更糟,因為它會被當成規則制度化。 是專家審查員在覆審「修正」時抓出來的:修正本身也要被審。
• 「解釋機制」比「寫對公式」更容易錯,而且更難被抓到:capture point 那段公式沒寫錯,但我給的物理解釋是「動能剛好被抬升重心的位能吃光」——而它的模型(定高線性倒單擺)假設重心高度固定,根本沒有位能變化,解釋跟自己引用的來源直接矛盾。正確機制是踩對地方讓發散模態的係數歸零,重心指數收斂。判斷法:要為一條公式配上「物理上是怎麼回事」的說法前,先確認那個說法在該模型的假設下成立——「能量守恆」「動能換位能」這類聽起來很自然的解釋最危險,因為讀起來太順,不會有人停下來檢查。

核心一句

每個技術主張,都要能追到出處、或可被驗證的依據——不靠「自言自語」。 這是這 repo 跟「看起來合理但沒根據」的內容最大的差別。

可重用

這套工作流已封裝成 skill first-principles-tech-notes,可套用到其他知識庫專案。