「對人類來說，Markdown 是優雅的排版文字；對 AI Agent 來說，沒有結構化 Metadata 的 Markdown 只是一串需要盲目猜測的字元流。」

🤯 為什麼預設的 Markdown 筆記會讓 AI Agent 卡關？

上一篇我們建立了 Go + Claude Code + Obsidian + Graphify 的四位一體技術選型。然而，當你真正讓 Claude Code 或 Go 程式去解析一篇標準的 Markdown 筆記時，如果沒有事先定義好 Frontmatter 規範，AI Agent 常會遇到以下痛點：

• 標題與檔名不一致（Naming Discrepancy）：
  檔名寫 channel-bug.md，內文 H1 寫 # Go Channel 阻塞調優，Agent 難以判定哪一個才是雙向連結 [[Link]] 的唯一真理（SSOT）。

• 標籤混亂與語意爆炸（Tag Pollution）：
  人類習慣隨手寫 #golang/concurrency/bug 或 #go-channel，如果沒有限制格式，AI Agent 在做分類或搜尋時會被幾百個微小差異的 Tag 淹沒。

• 上下文時序丟失（Temporal Loss）：
  AI 無法得知這篇筆記是「兩年前的舊技術決策」還是「昨天才發生的除錯紀錄」，導致提問時拿舊架構回答新問題。

為了解決這個問題，我們必須在 Obsidian 筆記頂部設計一套 「人類看得懂、Go 程式好解析、AI Agent 懂語意」 的標準化 YAML Frontmatter。

📋 1. 標準 YAML Frontmatter 格式設計

我們為 obsidian-agent-brain 系統定義的標準 YAML Frontmatter 格式如下：

---
id: "20260815-103000"
title: "Go Channel Timeout Prevention"
date: "2026-08-15"
type: "atomic-note"
status: "evergreen"
tags:
  - golang
  - concurrency
  - memory-leak
related:
  - "[[Golang Concurrency Patterns]]"
  - "[[Match Engine Performance]]"
aliases:
  - "Channel 超時防禦"
  - "Go Channel Timeout"
---

🔍 2. 核心 Metadata 欄位解析與設計哲學

為什麼選擇這些欄位？每一個欄位都精準對應到了 Go 程式處理 或 Claude Code 推理 的需求：

• id (絕對唯一識別碼)

  • 格式：YYYYMMDD-HHMMSS（例如 20260815-103000）。
  • 用途：
    • 當檔名因為重構而修改時，id 保持絕對不變。
    • Go CLI 可以在記憶體建立基於 id 的快速 Hash Map，提高全庫檢索效能。

• title 與 aliases (唯一標題與別名庫)

  • title：筆記的正統名稱，必須與 Obsidian 檔名完全一致。
  • aliases：Obsidian 原生支援的別名清單。
  • Agent 應用：當 Claude Code 閱讀雜亂草稿提到「Channel 逾時機制」時，能自動對照 aliases 庫，寫下精準的雙向連結 [[Go Channel Timeout Prevention|Channel 逾時機制]]。

• type (筆記類型與結構路由)
  明確定義筆記的生命週期型態，讓 Claude Code 知道該施加什麼樣的重構規則：

• status (知識熟成度)
  採用數位花園（Digital Garden）的知識成長模型，讓 AI 知道該筆記的信任度：
  • seed (種子)：剛從 Inbox 建立，資訊可能殘缺。
  • growing (成長中)：經過 Agent 重構，補全了部分連結與 Metadata。
  • evergreen (常青)：內容嚴謹完整，已成為穩定可靠的知識資產。

✍️ 3. 給 AI Agent 閱讀的「正文排版（Body）原則」

除了頂部的 YAML Frontmatter，Markdown 正文也需要遵循三個簡單的撰寫紀律：

• 善用 H2 (##) 作為語意區塊邊界

  Go 語言的 Markdown AST 解析器（如 goldmark）在切分文章區塊時，是以 Header 階層作為節點邊界的。規範只使用 ## 作為二級主題，能讓 Go CLI 輕鬆抽取特定的「代碼範例區塊」或「排查步驟區塊」。

• 程式碼區塊標註語言（Fenced Code Blocks）

  必須明確標註語言名稱（如 go 而非無名的 ）。這樣 Go 解析器在遍歷 AST 的 KindCodeBlock 時，能自動判斷這是一段 Go 代碼還是 Bash 指令，避免把代碼裡面的 // [[comments]] 誤判為 Obsidian 雙向連結。

• 一張筆記只保留一個 H1 (#)

  文章頂部只允許一個 # Title，且名稱必須與 Frontmatter 的 title 100% 相同。

🤖 4. 實戰：CLAUDE.md 中的 Validation Prompt 範例

為了讓 Claude Code 在執行 /refine-inbox 時嚴格執行這套規範，我們可以在專案根目錄的 CLAUDE.md 加上這一段 Prompt 規則：

## YAML Frontmatter Rules

When processing notes in `00_Inbox/`, you MUST ensure the final output contains a valid YAML Frontmatter at the very top:

1. `id` MUST be generated using timestamp format: `YYYYMMDD-HHMMSS`.
2. `title` MUST match the file name exactly.
3. `type` MUST be one of: [`atomic-note`, `adr`, `hub-note`].
4. `tags` MUST be lowercase, kebab-case array (e.g., `golang-concurrency`).
5. Scan existing vault note titles provided by `brain-cli`, and insert matching `[[Wikilinks]]` into the `related` field and body text.

💬 結語

有了這套 「人機共讀」 的 YAML Frontmatter 與筆記規範，我們的知識庫就不再是不可控的純文字，而是兼具 結構化資料庫（Structured DB） 與 非結構化文章（Markdown Text） 優點的強大知識體。

👉 明天 Day 05，我們將正式動手：「建立 obsidian-agent-brain Demo Repo 與開發環境搭建」。我們將把這個架構實體化，打造出第一個可運行的 Repository 骨架！我們明天見！