本章以 scripts/mdtools（blog 自己的 markdown 工具鏈，repo 內檔案）作為 concrete instance。讀者不需要事先熟悉 mdtools — 每段會先講通用 pattern，再用對應 code 示範一種可行實作。

基礎：為什麼需要 flag.NewFlagSet 而非 flag.Parse()

flag.Parse() 只解析一次全域 flag set。對只有一個命令的小工具（如 tool --input foo）夠用；但一旦進入 tool fmt --fix 這種 <tool> <subcommand> [flags] 結構，全域 flag set 就擋路：

• --fix 對 fmt 命令有意義，對 lint 命令沒有。
• 各子命令可能共享 name（例如 --verbose）但預設值或語意不同。
• help 輸出需要分子命令各自列自己的 flags。

flag.NewFlagSet 讓每個子命令擁有獨立的 flag 命名空間：

1fs := flag.NewFlagSet("fmt", flag.ExitOnError)
2fix := fs.Bool("fix", false, "apply fixes in place")
3check := fs.Bool("check", false, "report-only")
4_ = fs.Parse(args) // args = os.Args[2:]，已經跳過了子命令本身

fs.Parse(args) 只看傳進去的片段，不碰 os.Args 全域。這是撐起 subcommand CLI 的核心 API。

專案 Layout：main → cmd/ → internal/

Go 慣例的 CLI 專案結構是三層，對應三種責任：

 1scripts/mdtools/
 2├── main.go             ← 層 1：dispatcher，只做「看第一個參數分派到哪裡」
 3├── cmd/
 4│   ├── fmt.go          ← 層 2：每個子命令一個檔案，負責 flag 解析與呼叫 internal
 5│   ├── lint.go
 6│   ├── cards.go
 7│   └── migrate.go
 8└── internal/
 9    ├── mdfmt/          ← 層 3：純邏輯，不碰 flag、os.Args、os.Exit
10    ├── mdlint/
11    └── mdcards/

分層的目的是支援每層獨立的測試策略：

• layer 1：幾乎不測，因為只是 switch。
• layer 2：integration test（給定 argv、確認 exit code 與 stdout）。
• layer 3：unit test，純函式輸入輸出。後續模組的所有實作技術 — AST 整合、idempotent 改寫、graph 分析 — 都落在這層。

把 os.Exit / os.Args / os.Stderr 都擋在 layer 1-2，layer 3 就能用一般 table-driven test 測，不用起 subprocess。

Layer 1：main.go dispatcher

 1// scripts/mdtools/main.go
 2package main
 3
 4import (
 5	"fmt"
 6	"os"
 7
 8	"blog/scripts/mdtools/cmd"
 9)
10
11func main() {
12	if len(os.Args) < 2 {
13		usage()
14		os.Exit(2)
15	}
16
17	sub := os.Args[1]
18	args := os.Args[2:]
19
20	var exitCode int
21	switch sub {
22	case "fmt":
23		exitCode = cmd.Fmt(args)
24	case "lint":
25		exitCode = cmd.Lint(args)
26	case "cards":
27		exitCode = cmd.Cards(args)
28	case "migrate":
29		exitCode = cmd.Migrate(args)
30	case "-h", "--help", "help":
31		usage()
32	case "version":
33		fmt.Println("mdtools 0.1.0-dev")
34	default:
35		fmt.Fprintf(os.Stderr, "unknown subcommand: %q\n\n", sub)
36		usage()
37		exitCode = 2
38	}
39
40	os.Exit(exitCode)
41}

注意幾個 pattern：

• dispatcher 不做 flag 解析。args := os.Args[2:] 把剩下交給子命令。
• 每個子命令回傳 int，dispatcher 統一呼叫 os.Exit。這讓子命令本身容易測（不會直接 kill 測試 process）。
• -h / --help / help 三種寫法都接受。Unix 慣例。
• unknown subcommand 進 exit code 2，保留 exit 1 給「有違規」的語義。

Layer 2：子命令入口

每個子命令一個檔案，結構類似：

 1// scripts/mdtools/cmd/fmt.go
 2package cmd
 3
 4import (
 5	"flag"
 6	"fmt"
 7	"os"
 8
 9	"blog/scripts/mdtools/internal/files"
10	"blog/scripts/mdtools/internal/mdfmt"
11	"blog/scripts/mdtools/internal/rules"
12)
13
14func Fmt(args []string) int {
15	fs := flag.NewFlagSet("fmt", flag.ExitOnError)
16	fix := fs.Bool("fix", false, "apply fixes in place")
17	check := fs.Bool("check", false, "report-only; non-zero on pending changes")
18	_ = fs.Parse(args)
19
20	if *check && *fix {
21		fmt.Fprintln(os.Stderr, "mdtools fmt: --fix and --check are mutually exclusive")
22		return 2
23	}
24	if !*check && !*fix {
25		*check = true // safe default
26	}
27
28	paths := fs.Args()
29	if len(paths) == 0 {
30		paths = []string{"content"}
31	}
32
33	cfg := rules.Default()
34	mdFiles, err := files.WalkMarkdown(paths)
35	if err != nil {
36		fmt.Fprintf(os.Stderr, "mdtools fmt: walk error: %v\n", err)
37		return 2
38	}
39
40	changed := 0
41	for _, path := range mdFiles {
42		result, err := mdfmt.FormatFile(path, cfg)
43		if err != nil {
44			fmt.Fprintf(os.Stderr, "mdtools fmt: %s: %v\n", path, err)
45			return 2
46		}
47		if !result.Changed() {
48			continue
49		}
50		changed++
51		if *fix {
52			if err := os.WriteFile(path, result.Fixed, 0o644); err != nil {
53				fmt.Fprintf(os.Stderr, "write %s: %v\n", path, err)
54				return 2
55			}
56			fmt.Printf("fixed: %s\n", path)
57		} else {
58			fmt.Printf("would fix: %s\n", path)
59		}
60	}
61
62	if *check && changed > 0 {
63		return 1 // CI-friendly: exit 1 means "things need fixing"
64	}
65	return 0
66}

要注意幾個設計決策：

• flag 定義就在入口函式裡，不抽成 package 常數。每個子命令的 flag 獨立演化。
• ExitOnError 讓 fs.Parse 遇到不合法 flag 直接 exit — 對 CLI 工具 OK，因為 parse 失敗本來就無法繼續。測試時要用 ContinueOnError 避免殺測試。
• positional args 從 fs.Args() 取，不是 os.Args。fs.Parse 會把非 flag 的留在 fs.Args()。
• 預設值走安全側（*check = true when neither given）— 防止使用者意外執行破壞性動作。
• exit code 分層語意：0 = 成功、1 = 有違規、2 = 工具本身失敗。CI script 能用 [[ $? -eq 1 ]] 區分。

Layer 3：internal 實作

Layer 3 是純邏輯，不知道任何 os / flag 的存在。這讓它能被 layer 2 呼叫、被 test 呼叫、也能在未來被其他 binary 或 library 重用：

 1// scripts/mdtools/internal/mdfmt/fixer.go
 2package mdfmt
 3
 4import (
 5	"bytes"
 6	"os"
 7
 8	"blog/scripts/mdtools/internal/rules"
 9)
10
11type FixResult struct {
12	Path     string
13	Original []byte
14	Fixed    []byte
15}
16
17func (r FixResult) Changed() bool {
18	return !bytes.Equal(r.Original, r.Fixed)
19}
20
21func FormatFile(path string, cfg rules.Config) (FixResult, error) {
22	data, err := os.ReadFile(path)
23	if err != nil {
24		return FixResult{}, err
25	}
26	fixed := applyAll(data, cfg)
27	return FixResult{Path: path, Original: data, Fixed: fixed}, nil
28}

FormatFile 回傳 (FixResult, error)，不 os.Exit、不印訊息、不碰全域狀態。Test 可以直接給一個記憶體 []byte 跑 applyAll 驗結果。

什麼時候該上 cobra

升級到 cobra 的判準是stdlib 能處理的負面複雜度已經超過 cobra 的學習成本。下表列五個實際觸發過團隊升級的訊號，每個都附展開說明。

命令層級超過 3 層：kubectl get pods 只有兩層還撐得住；到 gh api repos owner/repo/pulls list --limit 10 就是四層（含 api 這個 namespace），dispatcher 裡巢狀 switch 開始難讀。信號：dispatcher 的 switch case 超過十個，或 case 裡面又呼叫另一個 switch。反例：即使只有兩層，若每層未來會繼續加，早上 cobra 可省後來重構。

需要自動 shell completion：end-user 會反覆打命令、需要 tab 補齊子命令與 flag 名稱時，這功能差很多。手寫 completion 腳本要處理三種 shell 的語法差異，成本高；cobra 一行 cobra.GenBashCompletion 就產生。信號：工具有外部使用者、或團隊已經裝 shell completion。反例：只在 CI 跑、人不會互動輸入。

man-page 形式的 help 輸出：Unix 社群期待工具有 man tool 級的文件。stdlib 只輸出簡單的 usage 字串，排版樸素；cobra 的 doc package 能生成 markdown / reStructuredText / man。信號：工具要 package 進系統（Homebrew、apt），或對外發佈。反例：公司內部用、README 夠用。

多 end-user 讀 help：工程師忍受樸素的 -h 輸出，但產品經理、SRE on-call 看不下。cobra 有明確的 long description、example 欄位，排版比 stdlib 好。信號：使用者包含非程式設計角色。反例：user 是同團隊工程師。

大量共用 flag：--verbose、--log-level、--config 這類 flag 每個子命令都要用。stdlib 要在每個子命令重複 fs.Bool("verbose", ...)；cobra 的 PersistentFlags 能繼承到所有 subcommand。信號：重複 flag 超過三個、或要 enforce 某個 flag 在所有 subcommand 都有。反例：flag 在每個子命令語意不同，共用反而製造混淆。

以上五個訊號在 mdtools 都沒命中（內部工具、單層 subcommand、工程師使用者），所以繼續走 stdlib。若未來 mdtools 對外釋出給讀者下載，就值得重新評估。判讀時機是設計當下，不是感覺「stdlib 開始髒」時 — 髒時通常已經晚。

常見陷阱

在 layer 3 直接呼叫 os.Exit

會破壞 test：test runner 呼叫 TestXxx 時，如果 subject code 裡 os.Exit(1)，整個 test process 退出，其他 test 不跑。Layer 3 應回傳 error，讓 layer 2 決定怎麼退出。

用全域 var fs = flag.NewFlagSet(...) 宣告 flag

每次呼叫會累積狀態（flag 已經被定義過會 panic），並且兩個 test 同時跑會 race。定義 flag 要在函式裡。

忘記 ContinueOnError 就跑 test

ExitOnError 是 production 預設，但測試時會讓測試 process 整個退出。Table-driven test 要用：

1fs := flag.NewFlagSet(name, flag.ContinueOnError)
2fs.SetOutput(io.Discard) // 測試時不要印 usage 到 stderr

太早抽出「所有子命令共用的 flag」

PersistentFlags 概念在 stdlib 沒有，手動在每個子命令重複 fs.Bool("verbose", false, ...) 看似重複但其實可讀。一旦抽成共用 helper，就開始維護一個小框架 — 這時候用 cobra 反而更乾淨。

擴充路徑

• 命令太多時分組：tool fmt check、tool fmt fix 的兩層 subcommand 可以用「每層一個 switch」展開，main → cmd.Fmt → cmd.FmtCheck。mdtools 的 migrate fix-links 就是這個模式（見 cmd/migrate.go）。
• 共用 config loading：rules.Default() 這類邏輯放在 internal 裡，每個子命令呼叫；不要每個子命令自己 parse 配置檔。
• 測試 layer 2：用 buffer 捕獲 stdout/stderr，傳入自定 args。參考 Go stdlib 的 testing/iotest 跟 bytes.Buffer。

下一步

9.2 goldmark AST 入門 會看 mdtools 怎麼把 markdown 解析成可操作的結構，layer 3 內部怎麼組織 parser 整合。

Go 的慣例是封一層薄 wrapper — 不讓呼叫端直接看到第三方 API 的完整型別空間，保留未來換 parser 的彈性。加上 Go 的 AST 節點通常區分 block 跟 inline 兩種型別（對應到 CommonMark spec），走訪時需要配合型別判讀，以免呼叫到只存在於 block 節點的 method（Lines() 就是典型例子，對 inline 節點呼叫會 panic）。

本章以 scripts/mdtools/internal/astutil 跟 internal/mdcards/graph.go 為 concrete instance 示範整合流程。更廣泛的 AST 概念背景在 什麼是 AST；本章聚焦 Go 層面的整合 pattern。

為什麼選 goldmark

Markdown parser 在 Go 有多個選項。選 goldmark 的理由：

• Hugo 內建用它 — 同一個 parser 解析，lint 結果跟 render 結果一定一致。其他 parser 可能判讀差異導致「lint 過了但 Hugo render 壞」的長尾 bug。
• 完整 CommonMark 支援 + GFM 擴充。table、strikethrough、task list 都在。
• AST 節點設計貼近 CommonMark spec：心智負擔小，節點型別直接對應 spec 用語。
• 純 Go、零 CGO、穩定。build 不會踩奇怪的 C 依賴。

類似選擇邏輯可套用到其他格式：Go 原始碼用 go/parser，YAML 用 gopkg.in/yaml.v3，protobuf 用 google.golang.org/protobuf/encoding/prototext。

最小整合：parse 一份 markdown

 1// scripts/mdtools/internal/astutil/parser.go
 2package astutil
 3
 4import (
 5	"github.com/yuin/goldmark"
 6	"github.com/yuin/goldmark/ast"
 7	"github.com/yuin/goldmark/extension"
 8	"github.com/yuin/goldmark/parser"
 9	"github.com/yuin/goldmark/text"
10)
11
12type Parser struct {
13	md goldmark.Markdown
14}
15
16func NewParser() *Parser {
17	md := goldmark.New(
18		goldmark.WithExtensions(
19			extension.GFM, // Table, Strikethrough, Linkify, TaskList
20		),
21	)
22	return &Parser{md: md}
23}
24
25func (p *Parser) Parse(src []byte) ast.Node {
26	reader := text.NewReader(src)
27	return p.md.Parser().Parse(reader, parser.WithContext(parser.NewContext()))
28}

為什麼包一層 Parser 而不是直接呼叫 goldmark.New(...).Parser().Parse(...)：

• 第三方 API 面積大，工具只需要其中一部分。封裝讓呼叫端看不到 goldmark.Markdown、parser.NewContext 這些細節。
• 未來換 parser 成本低：如果有天換 mistune-for-go 或自寫 parser，呼叫端的 astutil.NewParser().Parse(src) 不用改。
• 測試替身容易：unit test 可以 mock Parser interface。

三個 struct / package / extension 配置的預設值：

• Extensions：extension.GFM 涵蓋 blog 需要的全部；只啟用實際用到的 extension 讓 parser 行為可預測。
• Context：每次 Parse 都建新 context — goldmark context 儲存 parse 狀態，不能跨 parse 共用。

AST 節點階層：Block 跟 Inline 的分野

goldmark 的 AST 節點有兩大類，型別系統直接區分：

1// goldmark/ast/ast.go
2type NodeType int
3const (
4	TypeDocument NodeType = iota
5	TypeBlock
6	TypeInline
7)

Block 節點：段落、heading、list、table、blockquote、fenced code block — 在來源檔案中占據完整的行。這類節點帶有 source line segments，能用 n.Lines() 取得起訖位置。

Inline 節點：link、emphasis、text、code span、image — 存在於 block 節點內部。Inline 節點沒有獨立的 line segments；它們的位置由父 block 管理。

這個區分有個實戰後果。第一次寫 AST 走訪的人經常這樣寫：

1// WRONG: 對 inline 節點呼叫 Lines() 會 panic
2ast.Walk(doc, func(n ast.Node, entering bool) (ast.WalkStatus, error) {
3	link, ok := n.(*ast.Link) // Link 是 inline
4	if !ok {
5		return ast.WalkContinue, nil
6	}
7	segs := link.Lines() // panic: "can not call with inline nodes"
8	...
9})

Link 節點沒有 Lines()。正確做法是走上去找最近的 block 節點：

 1// scripts/mdtools/internal/mdcards/graph.go
 2func nodeLine(n ast.Node, src []byte) int {
 3	for p := n; p != nil; p = p.Parent() {
 4		if p.Type() != ast.TypeBlock {
 5			continue
 6		}
 7		segs := p.Lines()
 8		if segs != nil && segs.Len() > 0 {
 9			return lineNumber(src, segs.At(0).Start)
10		}
11	}
12	return 0
13}

這個 walk-up-to-block 模式在每個會操作 inline 節點的工具裡都會出現。初學者的第一個 goldmark panic 幾乎必然是這個。

ast.Walk visitor 模式

goldmark 用標準 visitor pattern 走 AST：

1ast.Walk(doc, func(n ast.Node, entering bool) (ast.WalkStatus, error) {
2	// entering == true：進入節點（DFS 下行）
3	// entering == false：離開節點（DFS 回溯）
4	return ast.WalkContinue, nil
5})

Walk status 三個常見值：

• ast.WalkContinue — 繼續深度優先走訪。
• ast.WalkSkipChildren — 跳過子樹，繼續走同層。適合當「處理完整個 Paragraph 就不用再進去找子 Link」。
• ast.WalkStop — 整個走訪中止。適合「找到第一個就結束」。

實戰中幾乎只處理 entering == true 的情境 — DFS 下行足以覆蓋多數規則。entering == false 的 post-order 位置保留給需要聚合子樹資訊的場景（例如計算子樹裡的 link 數量）。

實戰：抽出所有 Link 節點並計算位置

mdtools cards 要找所有相對連結。這是一個完整的 ast.Walk 應用：

 1// scripts/mdtools/internal/mdcards/graph.go
 2func (g *Graph) extractEdges(fn FileNode) {
 3	ast.Walk(fn.AST, func(n ast.Node, entering bool) (ast.WalkStatus, error) {
 4		if !entering {
 5			return ast.WalkContinue, nil
 6		}
 7		link, ok := n.(*ast.Link)
 8		if !ok {
 9			return ast.WalkContinue, nil
10		}
11		dest := string(link.Destination)
12		if isExternalOrAnchor(dest) {
13			return ast.WalkContinue, nil
14		}
15		target := resolveTarget(fn.Path, dest)
16		if target == "" {
17			return ast.WalkContinue, nil
18		}
19		g.Edges = append(g.Edges, Edge{
20			SourcePath:  fn.Path,
21			SourceLine:  nodeLine(n, fn.Src),
22			Destination: dest,
23			Target:      target,
24			DisplayText: string(link.Text(fn.Src)),
25		})
26		return ast.WalkContinue, nil
27	})
28}

關鍵操作：

• Type assertion 提前 filter：link, ok := n.(*ast.Link)。不是 Link 就直接 continue，不做無用工。
• 判讀早退：isExternalOrAnchor(dest) 先過濾 http:// 與 #anchor 這類不屬於 graph 的邊。
• 對 inline 節點取行號走 walk-up（上節講的 nodeLine）。
• text 要透過 link.Text(fn.Src) 取 — inline 節點的文字儲存為 source 的 byte segment，不是 string。link.Text() 需要帶 src 才能反推。

Byte offset 定位到行號

goldmark 的 source segment 用 byte offset 標註起訖。要轉成 1-based line number：

 1// scripts/mdtools/internal/mdcards/graph.go
 2func lineNumber(src []byte, offset int) int {
 3	if offset < 0 || offset > len(src) {
 4		return 0
 5	}
 6	line := 1
 7	for i := 0; i < offset && i < len(src); i++ {
 8		if src[i] == '\n' {
 9			line++
10		}
11	}
12	return line
13}

O(offset) scan。對 300-檔 / 每檔 500 行的 blog repo 夠快；若是幾千萬行的 codebase 才需要預建 line-offset table。

text.Segment 跟 byte slice 的對應

每個 block 節點的 Lines() 回傳 *text.Segments，裡面是多個 text.Segment{Start, Stop int}：

1// 取段落第一行的原始 byte 內容
2segs := paragraph.Lines()
3firstSeg := segs.At(0)
4lineBytes := src[firstSeg.Start:firstSeg.Stop]

這個 API 讓你能回頭看原始 source，而不是透過 AST 重新渲染。對 lint 工具（要報告精確位置、甚至 rewrite）很重要。

常見陷阱

對 inline 節點呼叫 Lines()

已經講過，補一句：不只 Link，還有 Text、CodeSpan、Emphasis、Image — 凡是 n.Type() == ast.TypeInline 都不能 Lines()。寫 rule 時永遠用 nodeLine helper。

忘記 GFM extension，Table 節點會少

預設 goldmark.New() 沒開 GFM。content 裡的表格會被當成普通段落 parse，ast.Walk 根本找不到 *extension.ast.Table 節點。永遠在 goldmark.WithExtensions(extension.GFM)。

用 string(src) 當作可變字串操作

goldmark 預期 src 在 Parse 過程中 保持不變。若要改動，應先讀 src、parse、收集位置、產生新 byte slice；以不可變輸入 + 新輸出替代 in-place mutation。

ast.Walk 忘記回傳 continue

1ast.Walk(doc, func(n ast.Node, entering bool) (ast.WalkStatus, error) {
2	if someCondition {
3		processNode(n)
4		// 忘記 return，編譯失敗；但加 return 0 會提前終止
5	}
6	return ast.WalkContinue, nil
7})

預設要回 ast.WalkContinue, nil。早退用 ast.WalkSkipChildren 或 ast.WalkStop，別用 bare return。

擴充路徑

• 解析自己的 Go 原始碼：改用 go/parser + go/ast。語法樹更複雜（型別、scope、import），但 visitor pattern 本質一樣。參考 gopls 或 stringer 的原始碼。
• 寫自訂 extension：goldmark 允許註冊 parse-time 與 render-time 的 extension（自己的 block / inline 語法、或接管某個節點的 render 行為）。但除非你的 markdown 有特殊語法（Hugo shortcode 之類），大多數工具不用走這層。
• AST 快照比對測試：用 go-cmp 比對 ast.Walk 抓出的節點序列；新版 goldmark 升級時能快速發現相容性問題。

下一步

9.3 AST 驅動的 idempotent 文字改寫 會接著看怎麼從「讀 AST」走到「改原檔案」— 這是 mdtools fmt --fix 的核心。

設計一個冪等的改寫流水線有三個配合層：策略選擇（AST round-trip / byte surgical / 混合）、rule 鏈順序（每條 rule 的輸出要是下一條的合法輸入）、context 重算紀律（行數變動後索引要重建）。本章依序展開這三層，並以 mdtools fmt --fix 的 applyAll 為 concrete instance。

改檔的三種策略

把 AST 資訊轉成檔案修改有三條路：

mdtools 選第三條。純 AST round-trip 在長尾場景（nested fence、特殊 escape）會產出跟 source 不等價的 markdown；純 byte-offset 讓 MD047（trailing newline）這類微瑣事變得囉嗦。混合讓每條 rule 在它最自然的層級解決。

設計原則：能用 line-based 就用，AST 只在真的需要語意判讀時才上。

Rule 鏈的結構

mdtools fmt 的 applyAll 是條流水線：

 1// scripts/mdtools/internal/mdfmt/fixer.go
 2func applyAll(data []byte, cfg rules.Config) []byte {
 3	lines := splitLines(data)
 4
 5	// MD026 — 標題結尾標點，line-preserving
 6	if cfg.Headings.ForbidTrailingPunct {
 7		ctx := AnalyzeLines(lines)
 8		lines = FixHeadingTrailingPunct(lines, ctx, cfg.Headings.ForbiddenTrailingPunct)
 9	}
10
11	// MD022 — 標題前後空行，line-count changing
12	if cfg.Headings.RequireBlankLines {
13		ctx := AnalyzeLines(lines)
14		lines = FixHeadingBlankLines(lines, ctx)
15	}
16
17	// MD031 — fenced code block 前後空行
18	if cfg.CodeBlocks.RequireBlankLinesAround {
19		ctx := AnalyzeLines(lines)
20		lines = FixFencedCodeBlankLines(lines, ctx)
21	}
22
23	// MD032 — 列表前後空行
24	ctx := AnalyzeLines(lines)
25	lines = FixListBlankLines(lines, ctx)
26
27	// MD060 — 表格對齊
28	ctx = AnalyzeLines(lines)
29	lines = FixTables(lines, ctx, cfg.Tables)
30
31	// MD034 — 裸 URL 縮短
32	ctx = AnalyzeLines(lines)
33	lines = FixBareURLs(lines, ctx, cfg.URLs)
34
35	out := joinLines(lines)
36	out = EnsureTrailingNewline(out) // MD047
37	return out
38}

幾個設計決策值得拆開看。

順序決定結果

Rule 順序有明確的依賴判準：每條 rule 的輸出應該是下一條 rule 的合法輸入。

• MD026 先跑：它改標題內容、不改行數，後面 rule 的行號不會位移。
• MD022 / MD031 / MD032 緊接著：這些都 insert blank lines，會改行數；但它們彼此之間不衝突（heading ≠ fence ≠ list）。
• MD060 表格對齊在 URL 縮短之前：讓表格先成為可解析結構，URL rule 才能正確判斷「這個 URL 在表格 cell 內」。
• MD034 URL 縮短最後：URL 變短會讓表格欄寬變化；但因為 MD060 已經做過對齊，後續工具會再跑一次 fmt –fix 重新對齊。這個「跑兩次才穩定」的特性是可接受的，因為 fmt –fix 本來就冪等。
• MD047 trailing newline 在 byte 層做，最後一步。

每條 rule 重新 analyze context

AnalyzeLines(lines) 在每個會變行數的 rule 之前重跑。為什麼：

• 上一條 rule 可能把 fence 或 front matter 位置推後。
• Context 裡的 Skip[]、FenceOpen[]、FenceClose[] 都是按行索引儲存。
• 行數改變 → 索引失效 → 必須重算。

成本是 O(N)，對 500-行檔案微秒級。在整體 pipeline 中可忽略。

Line-based rule 本體範例

以 MD022（標題前後空行）為例：

 1// scripts/mdtools/internal/mdfmt/rules.go
 2func FixHeadingBlankLines(lines []string, ctx LineContext) []string {
 3	if len(lines) == 0 {
 4		return lines
 5	}
 6	out := make([]string, 0, len(lines)+8)
 7	for i, line := range lines {
 8		isHdr := !ctx.Skip[i] && isHeadingLine(line)
 9
10		if isHdr && len(out) > 0 && !isBlank(out[len(out)-1]) {
11			out = append(out, "")
12		}
13		out = append(out, line)
14		if isHdr && i+1 < len(lines) && !isBlank(lines[i+1]) {
15			out = append(out, "")
16		}
17	}
18	return out
19}

關鍵 idempotent 技巧：

• 判斷「上一行不是 blank 就插」而非「永遠插」。已經插過 blank 的情況下，第二次跑會看到 blank，跳過，結果相同。
• out 是新 slice，不改動原 lines。函式純粹。
• look-ahead 看原 lines，避免剛插的 blank 讓邏輯誤判下一輪。

AST-guided rule 範例：MD034 URL 縮短

這條 rule 用 AST 找「哪些 text 是 link 之外的」，行內用 regex + mask 處理：

 1// scripts/mdtools/internal/mdfmt/urls.go
 2func rewriteBareURLsInLine(line string, cfg rules.URLRules, idPatterns []*regexp.Regexp) string {
 3	masked := collectMaskedRanges(line) // [...](/go/09-tooling-and-analysis/ast-idempotent-rewriting/...) / <...> / `...` 的位置
 4	matches := bareURLRe.FindAllStringIndex(line, -1)
 5	if len(matches) == 0 {
 6		return line
 7	}
 8	var b strings.Builder
 9	cursor := 0
10	for _, m := range matches {
11		start, end := m[0], m[1]
12		end = trimURLTrailPunct(line, start, end)
13		b.WriteString(line[cursor:start])
14		if inMasked(masked, start) {
15			b.WriteString(line[start:end]) // 已在 link / code span / 角括號內
16		} else {
17			rawURL := line[start:end]
18			display := shortenURL(rawURL, cfg, idPatterns)
19			fmt.Fprintf(&b, "[%s](/go/09-tooling-and-analysis/ast-idempotent-rewriting/%s)", display, rawURL)
20		}
21		cursor = end
22	}
23	b.WriteString(line[cursor:])
24	return b.String()
25}

這裡的 混合精神：

• AST 不直接改檔，只提供「這行的哪些 byte 範圍是 existing link / code span」的判讀（實際上這段用了 regex 模擬；真正嚴謹時會改用 AST 定位）。
• 真的改寫走字串層級，保留原格式。
• 已在 link 內的 URL 不再包第二層 — inMasked 檢查防止 double-wrap，這也是 idempotent 關鍵：第二次跑，所有 URL 都已經在 masked range 裡，跳過。

--check 跟 --fix 共用邏輯

一個常見反 pattern 是：check 模式重寫一次邏輯「看會不會改」，fix 模式真的改。兩套邏輯一旦漂移，誤報或漏報就出現。

正確做法是共用同一個 FormatFile，然後比對結果：

 1// scripts/mdtools/internal/mdfmt/fixer.go
 2func FormatFile(path string, cfg rules.Config) (FixResult, error) {
 3	data, err := os.ReadFile(path)
 4	if err != nil {
 5		return FixResult{}, err
 6	}
 7	fixed := applyAll(data, cfg)
 8	return FixResult{Path: path, Original: data, Fixed: fixed}, nil
 9}
10
11// check / fix 都呼叫 FormatFile，只差在怎麼處理結果
12func (r FixResult) Changed() bool {
13	return !bytes.Equal(r.Original, r.Fixed)
14}

子命令層處理差異：

 1// cmd/fmt.go 簡化版
 2result, _ := mdfmt.FormatFile(path, cfg)
 3if !result.Changed() {
 4	return // 沒改動，跳過
 5}
 6if *fix {
 7	os.WriteFile(path, result.Fixed, 0o644)
 8} else {
 9	fmt.Printf("would fix: %s\n", path)
10}

check 跟 fix 跑一模一樣的 rule chain，只是其中一個寫檔、另一個回報。這個結構讓兩個模式的行為保證一致。

Idempotent 的驗證方式

工具宣稱冪等，測試要驗證：

 1func TestFormatIdempotent(t *testing.T) {
 2	inputs, _ := filepath.Glob("testdata/*.md")
 3	cfg := rules.Default()
 4	for _, in := range inputs {
 5		data, _ := os.ReadFile(in)
 6		once := applyAll(data, cfg)
 7		twice := applyAll(once, cfg)
 8		if !bytes.Equal(once, twice) {
 9			t.Errorf("%s: not idempotent (applied twice != once)", in)
10		}
11	}
12}

生產環境的 pre-commit hook 本質上每次 commit 都在驗證冪等：

1. 作者寫 commit → fmt --fix 跑過 → re-stage
2. 如果邏輯不冪等，下次作者改同檔案，可能又會被改回/改去
3. 使用者很快會發現「為什麼這個工具一直來回改我的檔案」

冪等是 pre-commit 的信譽基礎。

常見陷阱

Rule 之間互相抵消

1Rule A: 移除行尾空白
2Rule B: 把每個 heading 後面補空格到 60 欄

A 跟 B 串起來會永遠改來改去。寫 rule 時要想「其他 rule 會對我的輸出做什麼」。

讀 src 跟改 src 用不同的 byte slice

在迴圈中一邊掃 data、一邊 append 到 out，中間忘了切換視角。建議永遠遵循 (原 lines, 新 out) 兩個名字，迴圈體只 look-back 到 out[len(out)-1] 或 look-ahead 到 lines[i+1]，絕不在同一時段既讀又寫同一 slice。

Trailing newline 的邊界

1bytes.TrimRight(data, "\r\n")      // 去掉全部
2return append(data, '\n')           // 加一個

空檔案要特別處理 — 加了 \n 就變非空。mdtools 的作法是：

1if len(data) == 0 {
2	return data
3}

空檔保持空。

Regex-based URL 偵測的邊界

Go 的 RE2 沒有 lookbehind，無法用 regex 直接寫「URL 不在 ]( 後面」。解法是先掃 mask（link span、angle bracket、code span），再跑 URL regex，match 結果對照 mask 決定是否替換。collectMaskedRanges 就是這個模式。

擴充路徑

• Rule dry-run diff：把每條 rule 單獨跑一遍，輸出每條 rule 改了哪幾個檔案。debug 為什麼某檔案被改時用得到。
• Configurable rule disabling：把 rule 開關改成 front matter 級別（mdtools-disable: MD026），讓個別檔案能 opt-out。
• Rule 可程式化插入：把 applyAll 改成「讀 config → 產生 rule list → iterate」，讓新 rule 不用改 fixer.go 而是註冊進來。

下一步

9.4 跨檔案圖分析 離開 single-file 世界，看 mdtools cards 怎麼建整個 repo 的 link graph 跑反向查詢。

這類分析的典型觸發點是需求已經離開 single-file 層：orphan 偵測（某個檔案是否被引用）、backlink 完整性（連結目標是否存在）、dependency cycle 檢測（import graph 是否有環）、unused export 偵測（某個 symbol 是否被使用）。每個都是圖論問題，需要先把 repo 結構化，單檔 walker 看不見跨檔 edge。本章以 mdtools cards（L1 連結有效性、L2 orphan 卡片、L4 卡片 K4 合規）作為 concrete instance。

為什麼要預先建圖而非每次 lint 都現查

直覺會說：對每個 link，直接 os.Stat(target) 看存在不存在，就能驗證 L1。

這個做法在 100 個檔案、每檔 10 個 link 時 OK — 1000 次 stat、每次 < 1ms，總計 1 秒內。但一旦要做 L2 「每張卡片至少被一篇正文引用」，問題就變成：

1for each card file C:
2  for each other file F:
3    parse F
4    for each link L in F:
5      if L points to C: mark C as referenced

N² parse，每次 parse 又走 AST。1000 檔 × 1000 檔 = 100 萬次 parse，每次 50ms，總計 14 小時。

解法是 parse 一次、存下所有 edge、在圖上查。Parse 是 O(N) 一次；所有後續 query 都在 in-memory map 上做，microseconds。

Graph 的資料結構

 1// scripts/mdtools/internal/mdcards/graph.go
 2type Edge struct {
 3	SourcePath  string // 包含連結的檔案
 4	SourceLine  int    // 連結所在行
 5	Destination string // link 目的地（原文）
 6	Target      string // 解析後的檔案路徑（可能不存在）
 7	DisplayText string // 顯示文字（反釣魚用）
 8}
 9
10type FileNode struct {
11	Path string
12	AST  ast.Node
13	Src  []byte
14}
15
16type Graph struct {
17	Files []FileNode  // 所有 .md 檔
18	Edges []Edge      // 所有相對連結
19
20	byPath   map[string]*FileNode // path → FileNode
21	inbound  map[string][]int     // target path → edge indices
22	outbound map[string][]int     // source path → edge indices
23}

設計重點：

• FileNode 保留 AST + src：後面 L4 檢查（卡片首段是否有鄰卡連結）需要重讀 AST，不想再 parse 一次。
• Edge 用 slice 儲存，index 走 map：比起直接用 map[string][]Edge，這個 layout allocation 少、GC 友善，也容易 sort 輸出。
• inbound / outbound 都預先建：L1 靠 outbound，L2 靠 inbound。一次 parse 把兩邊都填好。

Parse pipeline：兩段式確保指標穩定

 1// scripts/mdtools/internal/mdcards/graph.go
 2func BuildGraph(roots []string) (*Graph, error) {
 3	mdFiles, err := files.WalkMarkdown(roots)
 4	if err != nil {
 5		return nil, err
 6	}
 7
 8	parser := astutil.NewParser()
 9	g := &Graph{
10		byPath:   map[string]*FileNode{},
11		inbound:  map[string][]int{},
12		outbound: map[string][]int{},
13	}
14
15	// 第一段：parse 全部檔案，填 g.Files
16	for _, path := range mdFiles {
17		data, err := os.ReadFile(path)
18		if err != nil {
19			return nil, err
20		}
21		doc := parser.Parse(data)
22		node := FileNode{Path: path, AST: doc, Src: data}
23		g.Files = append(g.Files, node)
24		g.byPath[path] = &g.Files[len(g.Files)-1]
25	}
26
27	// 第二段：抽出 edge（此時 g.Files 大小已固定，指標穩定）
28	for _, node := range g.Files {
29		g.extractEdges(node)
30	}
31
32	return g, nil
33}

兩段式的理由：第一段邊 parse 邊 append，slice 可能重新分配 underlying array，之前取的 *FileNode 指標會失效。第一段收斂後才取指標，保證穩定。這是 Go slice 常見的事故。

如果用 []*FileNode（指標 slice）就沒這問題，但對這個情境 []FileNode 空間效率較好。兩種都 OK，選一種就要注意對應的陷阱。

L1：連結有效性（outbound 走訪）

最簡單的 graph query：對每個 edge，檢查 target 是否存在。

 1// scripts/mdtools/internal/mdcards/l1.go
 2func checkL1LinkValidity(g *Graph) []report.Violation {
 3	var out []report.Violation
 4	for _, edge := range g.Edges {
 5		if TargetExists(edge.Target) {
 6			continue
 7		}
 8		out = append(out, report.Violation{
 9			Path:  edge.SourcePath,
10			Line:  edge.SourceLine,
11			Rule:  "L1-broken-link",
12			Level: report.LevelError,
13			Message: fmt.Sprintf(
14				"broken link %q: target not found", edge.Destination,
15			),
16		})
17	}
18	return out
19}

TargetExists 試兩個候選路徑 — {target}.md 跟 {target}/_index.md，因為 Hugo 的 URL routing 對 content page 跟 section page 一視同仁：

1func TargetExists(target string) bool {
2	for _, cand := range []string{target + ".md", filepath.Join(target, "_index.md")} {
3		if info, err := os.Stat(cand); err == nil && !info.IsDir() {
4			return true
5		}
6	}
7	return false
8}

L2：orphan 偵測（inbound 反查）

「每張卡片至少被一篇非卡片文章引用」— 這是反向查詢：對每張卡片，看它的 inbound 有沒有來自「非卡片檔」的 edge。

 1// scripts/mdtools/internal/mdcards/l2.go
 2func checkL2Orphans(g *Graph, cardsRoot string) []report.Violation {
 3	inboundNonCard := map[string]int{}
 4	for _, edge := range g.Edges {
 5		targetMd := edge.Target + ".md"
 6		if !isCardPath(targetMd, cardsRoot) || isSectionIndex(targetMd) {
 7			continue
 8		}
 9		if isCardPath(edge.SourcePath, cardsRoot) {
10			continue // card-to-card 不算
11		}
12		inboundNonCard[targetMd]++
13	}
14
15	var out []report.Violation
16	for _, fn := range g.Files {
17		if !isCardPath(fn.Path, cardsRoot) || isSectionIndex(fn.Path) {
18			continue
19		}
20		if inboundNonCard[fn.Path] > 0 {
21			continue
22		}
23		out = append(out, report.Violation{
24			Path:    fn.Path,
25			Rule:    "L2-orphan-card",
26			Level:   report.LevelWarn,
27			Message: "card has no inbound link from non-card content",
28		})
29	}
30	return out
31}

設計取捨：

• Card-to-card 不算 inbound：依 spec，卡片應被「教學文章」引用證明使用場景；卡片互連只證明概念網路，不證明實用。
• Warn 而非 error：orphan 是內容覆蓋率訊號，不是格式錯誤；新卡片剛建時不該被擋 commit。
• _index.md 排除：section page 不是 card。

L4：AST 跟 Graph 混用

這條規則複雜：「卡片的首段跟『概念位置』section 都要各有至少一個鄰卡連結」。要用 graph 抓候選，再用 AST 精確判讀在哪個 paragraph / section 內。

 1// scripts/mdtools/internal/mdcards/l4.go
 2func checkL4K4Structure(g *Graph, cardsRoot, conceptHeadingTitle string) []report.Violation {
 3	var out []report.Violation
 4	for _, fn := range g.Files {
 5		if !isCardPath(fn.Path, cardsRoot) || isSectionIndex(fn.Path) {
 6			continue
 7		}
 8
 9		firstPara := firstBodyParagraph(fn.AST)
10		if !subtreeHasCardLink(firstPara, fn.Path, cardsRoot) {
11			out = append(out, report.Violation{
12				Path:    fn.Path,
13				Rule:    "L4-first-paragraph-no-card-link",
14				Level:   report.LevelWarn,
15				Message: "opening paragraph should link to an adjacent card",
16			})
17		}
18
19		section := headingSection(fn.AST, conceptHeadingTitle, fn.Src)
20		if len(section) == 0 {
21			out = append(out, report.Violation{
22				Path:    fn.Path,
23				Rule:    "L4-missing-concept-position",
24				Level:   report.LevelWarn,
25				Message: "card missing 概念位置 section",
26			})
27			continue
28		}
29		if !sectionHasCardLink(section, fn.Path, cardsRoot) {
30			out = append(out, report.Violation{...})
31		}
32	}
33	return out
34}

兩個 helper 展示 graph 跟 AST 的交界：

• firstBodyParagraph(doc) 用 AST 走第一個 Paragraph 節點（document 的第一個 top-level child）。
• subtreeHasCardLink(node, sourcePath, cardsRoot) 用 ast.Walk 在該節點下找所有 Link，再用 resolveTarget 判斷是不是指向卡片。

為什麼用 AST 而不是行號範圍：Hugo content 的卡片結構多樣，首段可能跨多行；用 paragraph.Lines() 也能拿到 byte range，但還要處理 list item、table row 這類邊界。直接走 AST 子樹是最穩定的做法。

反向索引的設計擴充：slug-based 啟發式

mdtools migrate fix-links 要處理「broken link 但作者其實想連到某個存在的檔案，只是路徑寫錯」。這需要額外一個 slug 反向索引：

 1// scripts/mdtools/internal/mdmigrate/fixlinks.go
 2func buildSlugIndexes(g *mdcards.Graph) (primary, normalized map[string][]string) {
 3	primary = make(map[string][]string)
 4	normalized = make(map[string][]string)
 5	for _, fn := range g.Files {
 6		base := filepath.Base(fn.Path)
 7		var slug, target string
 8		if base == "_index.md" {
 9			parent := filepath.Dir(fn.Path)
10			slug = filepath.Base(parent)
11			target = parent
12		} else {
13			slug = strings.TrimSuffix(base, ".md")
14			target = strings.TrimSuffix(fn.Path, ".md")
15		}
16		primary[slug] = append(primary[slug], target)
17		if norm := sectionPrefixRe.ReplaceAllString(slug, ""); norm != slug && norm != "" {
18			normalized[norm] = append(normalized[norm], target)
19		}
20	}
21	return primary, normalized
22}

查詢時走多層啟發式：

1. 精確 slug 命中（broker → content/backend/knowledge-cards/broker）
2. 數字前綴 normalized 命中（03-cpython-internals 找不到 → 試 cpython-internals → 命中 04-cpython-internals）
3. 卡片優先（多個 candidate 時選 knowledge-cards/ 下的）
4. 同頂層子目錄優先（source 在 content/go/... 時選 content/go/ 下的 candidate）

這四層啟發式把 143 個 multi-candidate 收斂到 0 個 ambiguous。啟發式的層層疊加是 static analysis 工具常見 pattern — 寫過 linter、LSP、refactoring tool 的人都會在類似的決策樹花時間。

Parse 成本的實務控制

跨檔分析一次要 parse 幾百個檔案。幾個優化：

• 只 parse 一次：Graph 建好後 L1 / L2 / L4 共用。呼叫端不該重建 Graph。
• concurrent parse（選擇性）：mdtools 目前單執行緒 parse ~400 檔案 < 1 秒，沒必要並發。若檔案過萬，用 golang.org/x/sync/errgroup + worker pool fan out。
• 避免記憶體持有：Graph 的 FileNode.Src 跟 AST 都持有 reference。如果 GC 壓力敏感，做完 L1-L4 後顯式 g = nil 或分段釋放。blog 這個規模沒必要。

常見陷阱

Slice append 失效的指標

上面提過 — 邊 append 邊取指標會炸。BuildGraph 的兩段式是標準修法。

filepath.Rel 在 root 外的 panic

1rel, err := filepath.Rel("/foo", "/bar")  // 不會 panic，回傳 "../bar"
2rel, err := filepath.Rel("foo", "../bar") // err != nil

跨 repo root 的 rel 路徑會回 error。graph 的 target resolution 要接住這個 error。

Symlink 的走訪

filepath.WalkDir 預設不跟隨 symlink。這對 blog repo OK（沒 symlink）；但對其他 repo（例如 monorepo 有 symlink 指到 sibling package）要用 filepath.Walk 或自己實作。mdtools 不處理這個情境。

Hugo 的 URL 路由細節

../broker/ 從 content/backend/knowledge-cards/_index.md 出發，Hugo 解析成 content/backend/knowledge-cards/broker（也就是 sibling card 的 URL）。從 content/backend/knowledge-cards/acme-automation.md 出發，同樣的 ../broker/ 卻解析成 content/backend/broker（錯誤，broker 不在 backend 直屬）。這是因為 Hugo 把內容頁 URL dir 當成「slug 的 URL 資料夾」，不是「檔案所在的資料夾」。做 target resolution 時要注意這一點，參考 resolveTarget() 的實作。

擴充路徑

• Ingest commit history：把 git commit 的時序資訊加進 graph，抓「這張卡片連結了一個之前存在但被刪掉的檔案」。需要整合 go-git。
• Parallel parse：大型 monorepo 的 lint 可用 worker pool 並行 parse。用 channel 把 parse 結果丟回 main，注意 goldmark context 不跨 goroutine。
• Graph visualization：把 graph 輸出成 Graphviz DOT 或 Mermaid，給作者看「這張卡片的 backlinks 是什麼」。有助於規劃內容修訂。

下一步

9.5 工具決策的 tripwire 跳出實作，看「什麼時候該從 regex 升級到 AST、什麼時候該從 Python 換到 Go」的決策方法。

9.1–9.4 講了怎麼寫 Go 工具。這一章退一步，看什麼時候該寫這個工具、什麼時候該升級既有工具。決策錯了，寫得多好都沒用。本章介紹 tripwire 決策法、WRAP 框架在技術決策的套用、以及用 blog 工具鏈選型作為 concrete instance。

為什麼需要 tripwire

「什麼時候升級」本身是決策。如果不做預設，會發生兩件事：

太早升級：每次問「該不該升」的時候都說「升吧反正不會錯」。結果工具複雜度爆炸，維護成本拖慢產品開發。

太晚升級：每次都說「regex 再撐一下就好」。結果工具的誤判累積，作者開始手動 override、skip lint、加例外，工具信譽破產。

Tripwire 是事前約定：「當以下條件之一命中，就重新評估是否升級」。這把「該不該升」從臨時直覺變成有根據的再評估。

這個概念在 Chip 與 Dan Heath 的《Decisive》裡有詳細討論 — tripwire 的要點是用事前的明確條件，取代事後的模糊直覺。

WRAP 框架套用到工具決策

WRAP = Widen options / Reality-test / Attain distance / Prepare to be wrong。對應到技術決策：

Widen options：不要只在「Go 還是 Python」之間選。多選項至少要有：

• 現有工具撐著（regex + shell）
• 半自動化（Python + regex，50 行腳本）
• 自訂工具（Python / Go + 適當 parser）
• 買服務（買現成 linter SaaS）
• 不解決（接受這個問題）

Reality-test：用數字跟樣本驗證假設。「regex 夠用」是假設，數字可能說「每 100 個 match 裡 15 個誤判」。

Attain distance：退一步看，如果這個工具三年後可能被捨棄，現在投入多少才合理。

Prepare to be wrong：先設 tripwire，萬一決策錯了也能及時 pivot，不會沉沒到底。

blog 的工具鏈決策用這個框架跑過一次，結論是 Go + goldmark。過程紀錄在 mdtools 設計，這裡只提煉可複用的決策 pattern。

三個實戰 tripwire

以下三組 tripwire 對多數內部工具都適用。遇到其中一個命中時，該花一小時重新評估現有工具是否夠用。

Tripwire 1：從 shell one-liner 升級到腳本

訊號：

• 同樣的 shell 指令在三個以上地方重複貼過
• 指令超過 3 個 pipe 或巢狀 subshell
• 指令的行為要根據環境（CI vs local）分支

升級方向：寫成 20-50 行 Python 或 Bash script，放進 scripts/。

反例：每次寫新 shell 命令都起腳本檔。常用的一行 grep 不需要變 script。

Tripwire 2：從 regex 升級到 parser / AST

訊號：

• Regex 需要「上下文判斷」（這個 match 在 code block 內嗎？在 HTML tag 內嗎？）
• 規則要處理嵌套結構（表格內的 link、code block 內的 heading）
• 誤報率超過 1% 或每週出現
• 新規則要知道「父節點」「子節點」（MD024 siblings_only 就是這類）
• 跨檔案的 graph 需求出現（backlink 分析、broken link 偵測）

升級方向：引入該格式的官方 parser（markdown → goldmark；YAML → gopkg.in/yaml.v3；Go → go/parser）。

反例：簡單的「每行開頭是 # 就當 heading」這類規則，regex 永遠夠用。不要為了「學 AST」硬上。

Tripwire 3：從腳本語言升級到 Go

訊號：

• 需要 parse 有官方 Go 實作的格式（goldmark、go/ast、protobuf 等）
• 需要跨平台分發單一 binary
• Python / Node 的啟動時間在 pre-commit 的 accumulated cost 已感
• 要整合到 Go 生態系（產生 Go 程式碼、讀 Go 原始碼）
• 團隊主要語言是 Go，Python 腳本的維護者變成單一瓶頸

升級方向：Go。

反例：臨時的資料轉換、一次性的 data migration、快速 prototyping — Python 永遠比 Go 快動筆。

實戰紀錄：blog 的三層升級

blog 的 markdown 品質工具鏈在一個 session 內走完三層升級。把這個時間線攤開當案例。

Layer 0：沒工具，靠 markdownlint IDE extension

狀況：IDE 裝 markdownlint extension，作者寫稿時看到 yellow underline 手動改。

出現什麼 tripwire：內容規模長大後，reviewer 收到 PR 發現 20 個 MD026 違規，手動改成 cognitive burden。更糟的是紅隊教材有平行結構（13 個案例各有 ### 弱點環節），被 MD024 誤判為重複，作者開始 ignore 警告。

升級驅動：Tripwire 2 命中（規則需要父標題上下文，siblings_only 規則 IDE 沒有）。決策：升級到自訂工具。

Layer 1 候選：Python + regex

狀況：50 行 Python 腳本，逐行 match。

為什麼沒選：兩個跨檔需求已經浮現 — 卡片雙向完整性、L1 link 驗證。這是 graph 需求，regex 做不到 (Tripwire 2 的後半段命中)。加上 blog 本身用 Hugo（Go 寫的，markdown 由 goldmark parse），用 Python 的 markdown parser 會有 render 跟 lint 判讀不一致的長尾風險。

這個評估花了約 15 分鐘，記錄在決策文件裡 — 重點是評估本身有 artefact 可追溯。

Layer 2：Go + goldmark

狀況：選 Go，因為 (a) goldmark 是 Hugo 的 parser，lint 結果跟 render 必然一致；(b) 跨檔 graph 分析用 Go struct 乾淨；(c) 單一 binary 方便接 pre-commit hook 跟 CI，不用擔心 Python 環境。

如何驗證決策正確：看三個月後的狀態 — 工具有沒有被 bypass？新規則加起來順不順？CI 有沒有反覆失敗？作者有沒有開始覺得工具阻礙產出？這些訊號都沒出現，表示決策有效。若有出現，就是 Tripwire 3 的反向觸發（「該降級回 Python」或「該拆成多個專門工具」），又要重新評估。

延遲決策的具體成本

常見反論：「不急，等真的需要再升」。問題是延遲本身有成本：

• Technical debt 複利：regex 工具越長越大，每條新 rule 都變難，最後要重寫時要一次 migration 所有 rule。
• 誤報侵蝕信譽：使用者每週看到工具報錯、檢查後發現是誤判，開始忽略工具。信譽一旦壞，再好的工具也沒用。
• Option value 流失：跨檔分析、graph 視覺化、CI 整合這些 downstream feature 都要在 AST 基礎上才能做；延遲升級等於延遲 feature 路徑。
• 機會成本複利：每週花 30 分鐘手動改 lint 誤判，一年累積 26 小時 — 比升級工具的 8 小時多 3 倍。

時間視角變長，升級的 NPV 幾乎永遠正。延遲不是零成本的預設，是要主動合理化的選擇。

為什麼 blog 不走「先 Python 再 Go」的雙階段

有個常見建議：「先用 Python 快速做出雛形，驗證概念後再用 Go 重寫」。這個建議對不確定需求的情境有效（「我們不知道要什麼工具」），對已知需求的情境是浪費。

blog 的狀況是已知：

• 要 markdown lint + 跨檔 graph + pre-commit + CI — 四個需求都很明確
• 目標語言（Go）已經確定（Hugo 生態、單一 binary 需求）
• 第三方 parser 選擇（goldmark）已經是最優解

在這些條件下，寫 Python 原型的唯一價值是「學 AST 概念」。但同樣學習也能直接用 Go + goldmark 完成。花兩倍時間寫兩遍只為了「先驗證」，邏輯不成立。

判準：需求越明確、目標語言越確定，雙階段越浪費；需求越模糊、選型還在評估，雙階段越值得。

決策的副作用：artefact

不管最終選什麼，決策過程本身要留下 artefact。blog 案例裡的 artefact：

• mdtools 設計紀錄：為什麼是 Go、為什麼是 goldmark、tripwire 怎麼設的
• 什麼是 AST：AST vs regex 的概念說明
• markdown 寫作規範：工具要滿足的契約

三個文件加起來約 900 行，寫作時間不到半天。

為什麼留 artefact 比決策本身更重要：

• 半年後同樣問題再浮現時，不會重跑一遍評估
• 新加入的協作者能快速跟上決策脈絡
• Tripwire 條件寫下來才能被驗證（「三個月後有沒有命中？」）
• 反面證據出現時（例如發現 goldmark 有 bug），有清楚的位置記錄 revised decision

沒 artefact 的決策基本上等於沒做過。決策是動作，artefact 才是沉澱。

常見陷阱

把 tripwire 設太低

「每週誤判一次就升級」實務上等於「每週升級」。Tripwire 要設在真的造成信譽或產出瓶頸的位置。

把 tripwire 設太高

「等到 50% 誤判才升級」就太晚了 — 信譽早就垮了。合理範圍是 1-5% 誤判，或每週一次以上。

用 tripwire 取代日常 review

Tripwire 是「提醒重新評估」，不是「自動升級」。命中時要花時間評估，可能發現「還不該升，因為還有 X 原因」。Tripwire 是重新思考的觸發，不是自動化決策。

忽視已命中的 tripwire

「這個誤判已經出現第四週了，但我還是覺得先不要升」— 這是在告訴自己原本的 tripwire 設錯了，不是在等更好的時機。重新評估 tripwire 本身，不是 ignore。

擴充路徑

• Decision log 範本：把團隊的決策過程寫成 template，讓下次不用從零開始
• Post-mortem of decisions：決策後三個月回頭看，把「當時怎麼想」跟「現在怎麼看」對照
• Pre-mortem 技巧：決策前假設「三個月後這決定被推翻，最可能的原因是什麼」，當成補充 tripwire

下一步

9.6 pre-commit hook 與 CI 整合 回到工程落地，看工具怎麼從 binary 變成 commit 與 CI 流程裡的執行體。

工具一旦從 CLI 進入 hook / CI，就有幾個容易出狀況的邊界：哪些 check 該放 hook（快、本地可執行）、哪些該放 CI（慢、需要乾淨環境）、hook 改了檔怎麼 re-stage、–no-verify 的邊界怎麼約定、CI strict mode 跟 local dev 的差異怎麼處理。本章展開這些問題，並以 .githooks/pre-commit + .github/workflows/md-check.yml 作為 concrete instance。

Pre-commit hook 能做什麼、不該做什麼

能做：

• 讀 staged 檔案，跑 lint / fmt
• 自動修正格式違規、git add re-stage
• 擋下 lint error 的 commit
• 跑跨檔分析（cards）
• 執行 build（確保程式碼能編譯）

不該做：

• 執行完整 test suite（太慢，交給 CI）
• 執行 e2e 或需要網路的操作（脆弱，commit 不該依賴外部）
• 修改未 stage 的檔案（會造成 working tree 混亂）
• 執行超過幾秒的任務（心流殺手）

原則：pre-commit 是快速守門員，不是完整驗證器。該做的 checks 要在秒級完成；更慢的驗證交給 CI。

Makefile 作為 hook 與 CI 的共同介面

有個常被忽略的 pattern：hook 跟 CI 都透過 Makefile 呼叫工具，不直接呼叫 binary。這讓三方共用同一套指令。

 1# Makefile
 2MDTOOLS_SRC := $(shell find scripts/mdtools -type f -name '*.go' 2>/dev/null)
 3MDTOOLS_MOD := scripts/mdtools/go.mod scripts/mdtools/go.sum
 4MDTOOLS_BIN := bin/mdtools
 5
 6.PHONY: build check fix lint cards install-hooks
 7
 8build: $(MDTOOLS_BIN)
 9
10$(MDTOOLS_BIN): $(MDTOOLS_SRC) $(MDTOOLS_MOD)
11	@mkdir -p bin
12	@cd scripts/mdtools && go build -o ../../$(MDTOOLS_BIN) .
13
14check: build
15	@./$(MDTOOLS_BIN) fmt --check content/
16	@./$(MDTOOLS_BIN) lint content/
17	@./$(MDTOOLS_BIN) cards content/
18
19install-hooks:
20	@git config core.hooksPath .githooks

這樣：

• 開發者本機：make check 手動驗一次
• Pre-commit：hook 呼叫 ./bin/mdtools ...（或透過 Makefile target）
• CI：workflow 跑 make check
• 所有人看到的失敗訊息格式一致

Make 的依賴 timestamp 機制也剛好解決「binary 什麼時候重 build」— MDTOOLS_BIN 依賴 MDTOOLS_SRC，source 新於 binary 才重 build。

Pre-commit hook 實作

 1#!/usr/bin/env bash
 2# .githooks/pre-commit
 3set -euo pipefail
 4
 5MDTOOLS_BIN="bin/mdtools"
 6REPO_ROOT="$(git rev-parse --show-toplevel)"
 7cd "$REPO_ROOT"
 8
 9# 沒 staged .md 快速退出
10staged_md=$(git diff --cached --name-only --diff-filter=ACMR | grep -E '\.md$' || true)
11if [[ -z "$staged_md" ]]; then
12    exit 0
13fi
14
15# Rebuild if source newer than binary
16if [[ ! -x "$MDTOOLS_BIN" ]] || [[ -n "$(find scripts/mdtools -type f -name '*.go' -newer "$MDTOOLS_BIN" 2>/dev/null || true)" ]]; then
17    echo "[pre-commit] rebuilding mdtools..."
18    (cd scripts/mdtools && go build -o "$REPO_ROOT/$MDTOOLS_BIN" .) || {
19        echo "[pre-commit] mdtools build failed" >&2
20        exit 1
21    }
22fi
23
24# fmt --fix on staged，re-stage 變動的檔案
25echo "[pre-commit] mdtools fmt --fix"
26while IFS= read -r f; do
27    [[ -z "$f" ]] && continue
28    before=$(git hash-object "$f")
29    "$MDTOOLS_BIN" fmt --fix "$f" >/dev/null
30    after=$(git hash-object "$f")
31    if [[ "$before" != "$after" ]]; then
32        git add "$f"
33    fi
34done <<< "$staged_md"
35
36# lint on staged (擋錯)
37echo "[pre-commit] mdtools lint"
38"$MDTOOLS_BIN" lint $staged_md || exit 1
39
40# cards on full content (擋錯)
41echo "[pre-commit] mdtools cards"
42"$MDTOOLS_BIN" cards content/ || exit 1
43
44exit 0

幾個關鍵 pattern：

Fast exit when no markdown staged

沒 md 改動時 hook 在 10ms 內退出。Go 工程師改 .go 檔時不會被 markdown hook 擋。這是使用者體驗的生死線。

git diff --cached --diff-filter=ACMR

• A (added), C (copied), M (modified), R (renamed) — 該檢查的變動類型
• 排除 D (deleted) — 刪除的檔案不用 lint

git hash-object 偵測實際變動

1before=$(git hash-object "$f")
2./bin/mdtools fmt --fix "$f"
3after=$(git hash-object "$f")
4[[ "$before" != "$after" ]] && git add "$f"

只在檔案內容實際改變時 re-stage。如果 fmt --fix 跑完沒改東西（檔案已經 compliant），不觸發多餘 git add。

避免用 stat 或 mtime — 那些會誤判（file touched 但內容相同）。

分層 exit code

• Fast exit (exit 0)：沒事要做
• Lint error (exit 1)：違規，擋 commit
• Build failure (exit 1)：工具壞了，擋 commit（比讓人用壞工具好）

Git 看 non-zero 就會阻止 commit，訊息會印到 terminal，作者能看到原因。

CI workflow

CI 跑得比 hook 更嚴格：

 1# .github/workflows/md-check.yml
 2name: md-check
 3
 4on:
 5  push:
 6    branches: [main]
 7  pull_request:
 8    branches: [main]
 9
10jobs:
11  md-check:
12    runs-on: ubuntu-latest
13    steps:
14      - uses: actions/checkout@v4
15      - uses: actions/setup-go@v5
16        with:
17          go-version-file: scripts/mdtools/go.mod
18          cache-dependency-path: scripts/mdtools/go.sum
19      - name: Build mdtools
20        run: |
21          mkdir -p bin
22          (cd scripts/mdtools && go build -o ../../bin/mdtools .)
23      - name: fmt --check
24        run: ./bin/mdtools fmt --check content/
25      - name: lint
26        run: ./bin/mdtools lint content/
27      - name: cards
28        run: ./bin/mdtools cards content/

設計決策：

go-version-file: scripts/mdtools/go.mod

讓 CI 從 go.mod 讀取 Go 版本。go.mod 裡寫 go 1.25.1，CI 自動用匹配的版本；本機升 Go 時 workflow 跟著同步。

CI 用 --check 而非 --fix

CI 的角色是偵測，修復留給本機。--check 發現問題就 fail，讓作者在本機修完再 push。若 CI 自動 --fix 然後 commit，會造成「CI 偷改作者 PR」的混亂。

不寫 try-catch 吞錯

CI 步驟失敗就 fail — 不要寫 continue-on-error: true 藏錯誤。早期接工具時覺得「讓 CI 通過先」很誘人，但藏錯誤等於工具沒生效。寧可 CI 紅，也要誠實。

安裝 hook 的 UX

.githooks/pre-commit 放進 repo，但 git 預設看 .git/hooks/，不會自動啟用。要跑：

1git config core.hooksPath .githooks

包成 Makefile target：

1install-hooks:
2	@git config core.hooksPath .githooks
3	@echo "hooks installed"

README 或 CONTRIBUTING.md 要寫「新 clone 時執行 make install-hooks」。這是一次性動作，但必要。

考慮過的替代方案：

• 放 .git/hooks/pre-commit — 不能 commit 進 repo，每個 clone 都要重設
• 用 husky / pre-commit 等工具 — 增加依賴，值得與否看團隊
• 用 direnv .envrc 自動設定 — 依賴 direnv，非標準

最乾淨是 Makefile target + 明確的 onboarding 步驟。

不能繞過的邊界

Pre-commit hook 可以用 --no-verify 跳過。規範要明寫：

寫作時遇到 pre-commit 報錯：讀錯誤訊息並修正，不可用 --no-verify 繞過 hook。

這是社會規範而非技術強制 — 技術上 git 一定允許 --no-verify。但只要規範明列、有人做 code review 抓到違規，就足夠維持紀律。

有個 nuance：緊急情況真的需要 --no-verify 怎麼辦？例如在服務中斷時要緊急 commit 修復。規範要留這個緊急閥門，但搭配：

• 事後必須補 commit 把違規修掉
• --no-verify 的使用要 log 或在 PR 描述標註

大多數 repo 一年可能用不到兩次。關鍵是預設是不繞過，而不是「看情況」。

常見陷阱

Hook 執行時間爆炸

常見在 cards 這類需要 parse 全 repo 的 check。對 400 檔 < 1 秒可接受；對 10000 檔就要評估。降級手段：

• cards 只跑受影響的子圖（根據 staged 檔案 inferrence）
• 複雜 check 搬到 CI
• 本機加 cache（invalidate on file mtime）

Binary 不 commit 進 repo，但 CI 失敗

.gitignore 排除 bin/，所以 CI checkout 時沒有 binary。要記得在 CI 加 build step（上面 workflow 的 Build mdtools step）。

fmt –fix 後 commit 有兩個版本

若 hook 的 fmt --fix 改了檔但 re-stage 失敗（例如 permission 問題），作者以為 commit 成功但實際 commit 的是舊版本。每次 staged 版本跟 working tree 都要同步 — git hash-object 比對能早期發現不一致。

Hook 不能跨平台

macOS / Linux 的 bash hook 在 Windows（未裝 WSL 或 Git Bash）可能不執行。如果 contributor 有 Windows，把 hook 寫成 Go 程式（例如 bin/mdtools hook pre-commit），讓 Go 本身處理跨平台。

擴充路徑

• Hook 只跑 staged 子圖：根據 staged files 推算需要 parse 的 repo subset，降低 hook 延遲。
• CI artifact 留 report：把 lint / cards 的報告 upload 成 GitHub Actions artifact，讓 PR 評論能連結到完整報告。
• Pre-push hook 做更重檢查：把 full test suite 放 pre-push（本機 push 前跑），更頻繁的 pre-commit 只做格式與 lint。

模組總結

走完九個章節，回到出發點：Go 除了寫後端服務，還能寫內部工具 / 靜態分析 / CLI / 程式碼生成。跟後端服務的差異在於生命週期、I/O 模式、錯誤處理慣例，但共用的 Go 技能（型別、interface、package、error）完全可遷移。

本模組介紹的技術 — stdlib flag、goldmark AST、idempotent rewriting、graph analysis、tripwire 決策、pre-commit 整合 — 適用範圍不只 markdown 工具。寫 linter、codegen、migration tool、build tool、dev helper 都是這些技術的組合。

下一步：動手把 scripts/mdtools clone 出來，加一條自己的 rule 進去。真正讀懂一個工具的方式是改它一次。

工具類跟服務類的差異常被隱晦地帶過，於是後端工程師轉寫工具時會帶進服務的慣性（長時 goroutine pool、defensive 錯誤降級、龐大依賴樹），讓工具變得重而難維護。把分野講清楚比給 cheatsheet 有用 — 後續每個模式落地時，讀者自己會判斷該採哪套預設。

業界哪些人在用 Go 寫工具

下列工具都用 Go 寫成，讀者多半每天都在使用或間接依賴它們：

• hugo — 靜態網站產生器，parse markdown + render template + serve dev。
• kubectl / helm — Kubernetes 的 CLI 客戶端，parse YAML + call API + render output。
• terraform — 基礎設施描述語言的 interpreter + state management。
• gh — GitHub CLI，把 REST/GraphQL API 包成命令列操作。
• goldmark — CommonMark parser，提供 AST 給其他 Go 程式使用。
• stringer / gopls — Go 官方工具鏈，分析 Go 原始碼並產生程式碼或語言服務。
• golangci-lint — 聚合多個 Go linter 的 runner。
• caddy / traefik — 雖然是服務，但以 CLI-first 配置見長。
• protobuf / grpc 的 code generator — 讀 IDL、吐 Go 程式碼。

這些程式都享受 Go 的幾個特定優勢：單一 binary 跨平台部署、快速啟動、stdlib 的 I/O 與檔案系統支援、goroutine 讓 pipeline fan-out 便宜、型別系統防止參數解析等瑣碎錯誤。

工具類 Go 跟服務類 Go 的結構差異

多數後端工程師轉去寫工具會遇到幾個慣性衝突。本節列五個最明顯的。

生命週期：短命而非長時

服務類 Go 跑起來就不預期結束 — goroutine pool、connection pool、graceful shutdown、health check 都繞著「長時健康運行」打轉。工具類 Go 預設是執行、完成工作、退出：

1func main() {
2    if err := run(); err != nil {
3        fmt.Fprintln(os.Stderr, err)
4        os.Exit(1)
5    }
6}

沒有 for { select {} } 的主迴圈，也不用註冊 signal handler 做 graceful 收尾（OS 會幫你回收檔案描述子）。延伸影響：

• 錯誤處理偏向中斷：服務類在錯誤時常選擇降級、記錄、繼續；工具類多半直接退出並印訊息，交給呼叫者決定下一步。
• goroutine 用法保守：工具很少要 100 個並發 worker。有也多半是 pipeline 的 fan-out，而非長時 pool。
• context 用法簡單：很少需要 context.WithCancel，context.Background() 經常夠用。

輸入輸出：檔案 / stdin / 命令列，而非 HTTP / queue

服務讀 request body、寫 response JSON、從 queue 拉訊息。工具讀檔案、parse 命令列 flag、接 stdin pipe、寫 stdout。這改變了幾個預設：

• 輸入格式多元：工具常處理 markdown、YAML、CSV、純文字；encoding/json 是基礎而非核心，其他 parser 反而更常用。
• os.ReadFile / os.WriteFile / filepath.WalkDir 是主力。Path 處理（filepath.Rel、filepath.ToSlash）會反覆出現。
• stdout 是結果通道。服務的 log 跟 response 是兩條 stream；工具的 log 跟 output 經常搶同一條 stream，需要嚴格 discipline：log 全部走 stderr，output 走 stdout，讓使用者能 pipe。

錯誤處理：accumulate or fail-fast

服務處理單一 request 時 fail-fast 容易（回 500、log 原因）。工具常一次處理多個輸入（批次 lint 300 個檔案），需要決定：

• Fail-fast：第一個錯誤就退出 — 適合 make check 這類 gate。
• Accumulate：蒐集全部錯誤一起報告 — 適合 lint 這類讓使用者看全貌的模式。

mdtools lint 就選 accumulate：一次 parse 全部 content，收齊所有 violations，sort 後輸出，退出碼反映是否有 error。作者可以一次看到所有問題，不用反覆跑。

依賴管理：盡可能 stdlib

服務的 go.mod 動輒幾十個 require — ORM、HTTP router、metrics、tracing、queue client 全要。工具圈文化明顯保守：

• 很多優秀 Go CLI 工具只有 1-3 個 direct dependency。
• 標準選型是先看 flag + os + filepath + encoding/* 能否滿足。
• 確實需要外部 parser、terminal UI、或結構化資料函式庫時才引入，而非預設。

這個 convention 出於實用考量：工具經常作為單一 binary 發佈，依賴越少、build 越快、跨平台問題越少。

部署：binary 而非 container

服務類部署到 k8s，工具類部署成 go install example.com/tool@latest 的 binary。連帶的預設：

• 配置用 CLI flag + 環境變數覆蓋：真正需要結構化配置時才引入 config schema。
• 版本管理用 build tag：go build -ldflags "-X main.Version=..." 把版本刻進 binary。
• 升級由 go install 承接：使用者重跑 go install 拉最新版，end-user 工具（hugo / kubectl）才額外設計自更新。

工具選型的判讀表

工具語言選型的核心判準是工作負載特徵：要不要跨平台分發、要不要處理大量 I/O、要不要整合既有生態。下表給八個判讀情境，各自有展開說明。

單一 binary 跨平台分發：工具的使用者可能分散在 macOS / Linux / Windows，每個人的 runtime 版本不同。Python 工具要求受眾先裝 Python、確定 3.x vs 2.7、管好 venv；shell 工具在不同 shell（bash / zsh / dash）行為分歧。Go 的靜態編譯讓一個 binary 直接丟出去能跑，這是推廣一個工具時最大的摩擦減法。適用信號：使用者超過 3 人、或使用者非工程師。反例：只在 CI 環境跑的 hook，runtime 已經固定，shell / Python 成本低。

大量檔案 I/O + 併發加速：linter 跑 1000 個檔案、migration 處理 10000 個 record，都是 I/O 密集任務。Go 的 goroutine + channel 讓 pipeline fan-out 極便宜，shell 靠 xargs -P 也能做但錯誤處理很脆弱；Python 的 GIL 限制真併發，得靠 multiprocessing 增加複雜度。信號：處理量超過「等半秒等得住」、或錯誤需要結構化蒐集。反例：處理一次、規模小於 100 檔，shell 反而快。

Parse 複雜格式：markdown、YAML、protobuf、Go 原始碼這類格式需要完整 parser，自己寫 AST walker 成本高。Go 有大量成熟 parser（goldmark、x/net/html、go/parser）可直接 import；shell 靠 grep / awk 拼不出正確解析；Python 的對應 parser（mistune、lxml）也成熟但跟 Go 生態隔離。信號：錯誤率 regex 已經解不乾淨。反例：純粹的文字搜尋 / 取代，regex 穩定勝出。

整合 Go 生態：要讀 Go 原始碼（gopls、stringer）、要跟 Hugo / Kubernetes 控制平面互動、要產生 Go 程式碼。這些場景跨語言整合成本高（要 FFI 或 serialization 橋接），Go 原生最直接。信號：上游依賴是 Go 專案、或產出物是 Go 程式碼。反例：跟 Python / JavaScript 生態為主時，用該語言更順。

一次性 one-liner：要做的事 grep / sed / awk 十行內能解決，沒有可觀的重複執行需求。用 Go 寫等於建立一個新 binary、build pipeline、版本管理 — 投資回不來。信號：命令能在 shell 下一口氣打完。反例：同樣 logic 要在三個地方重複貼，就該升級成腳本。

要用 ML / 資料科學套件：PyTorch、pandas、scikit-learn 沒有 Go 生態等價物。Go 有 gonum、但離 Python ML stack 的工具豐富度差一個數量級。信號：要調 model、做 EDA、畫圖表。反例：只是簡單統計彙總，Go 夠用。

快速 prototype、throw-away 腳本：動筆成本比 runtime 效能重要。Python 寫一個 50 行 script 的心智負擔比 Go 低（不用宣告型別、不用 import 大堆 package、REPL 可探索）。信號：要先弄清楚問題形狀。反例：prototype 很快會變成正式工具，Go 直接上反而省重寫。

需要 REPL 互動探索：Python / Node / Clojure 有成熟 REPL 文化，能邊試邊寫；Go 的 REPL 工具（yaegi 等）存在但非主流。信號：要實驗資料結構、API 行為、或設計決策。反例：解法已確定，不需要試 — Go 的 test-driven 小程式效果也不差。

mdtools 作為本模組的 worked example

本模組每一章講一個可複用的工具開發技術，同時用 scripts/mdtools（blog 自己用的 markdown 品質工具鏈，實體檔案在本 repo）作為 concrete instance。讀者不需要預先熟悉 mdtools — 每章會先講通用 pattern，再用 mdtools 的對應 code 示範一種可行實作。以下是 mdtools 的全貌，方便後面章節引用時有背景：

• 目的：保證 blog 的 content/**/*.md 在 commit 前符合規範文件（content/posts/markdown-writing-spec.md）的所有約束。
• 結構：單一 binary bin/mdtools，三個子命令 — fmt（格式修正）、lint（結構檢查）、cards（跨檔完整性）、加一個 migrate（一次性批量修正）。
• 實作層：
  • internal/mdfmt — 行為層 format rule，idempotent。
  • internal/mdlint — AST 層結構 rule，只報告。
  • internal/mdcards — 跨檔 link graph，報告 L1 / L2 / L4 違規。
  • internal/mdmigrate — 讀 graph、計算可自動化的修復、改檔。
• 依賴：stdlib + github.com/yuin/goldmark + github.com/mattn/go-runewidth（僅此三個 direct）。
• 整合：.githooks/pre-commit 跟 .github/workflows/md-check.yml 讓工具在每次 commit / push 都跑。

本模組的章節會逐層展開這些實作背後的 Go 技術。

下一步

進入 9.1 stdlib flag 做 subcommand CLI 開始看具體實作。