問題定位

文章模板的責任是穩定作者流程，正文的責任是承載技術文章本身。讀者進入文章時，需要看到概念、判讀、取捨與路由；作者在寫作時，需要一組欄位檢查文章是否具備可維護的最低結構。

本 blog 同時由人類作者、Claude Code 與 Codex 協作產生內容。模板若只放在單一 agent 的設定裡，就會形成工具分岔；模板若直接放進 backend 正文，又會把作者工作流暴露成讀者負擔。因此模板的單一真實來源放在 content/posts/，作為本 blog 專屬的寫作設定記錄。

放置決策

模板放置位置的核心判準是讀者與維護者是否一致。backend 文章面向技術讀者，report 面向可重用事後檢討，posts 面向 blog 自身的規範、設計與工具鏈紀錄。

位置適合內容本議題判斷
content/backend/技術文章正文、概念推導、案例分析保持讀者主線，作者模板留在上游
content/report/從具體 case 抽出的工程原則可寫抽象原則，操作模板留在 posts
content/posts/blog 規範、設計決策、工具鏈契約作為模板設計的 SSoT
.claude/Claude Code 執行規則可引用本文，本文維持語意來源
.codex/Codex 執行規則可引用本文，本文維持語意來源

這個分工讓模板同時支援 Claude Code 與 Codex，也保留文章對讀者的自然技術敘事。

模板責任

模板是品質閘門，責任是讓文章保留關鍵判準。它要檢查文章是否具備責任、判讀、風險、邊界與下一步路由，正文仍用技術文章的推導順序排列。

模板欄位作者要回答的問題正文呈現方式
責任這篇文章解決哪一類工程問題概念定位或開頭原則段
判讀讀者如何知道自己遇到這個問題核心判讀、判讀訊號、表格
風險判讀錯誤或缺漏會造成什麼代價風險段、反模式、情境段
邊界這篇文章處理到哪裡，交給誰接續交接路由、與其他章節分工
回寫案例或事故教訓應回寫到哪個章節下一步路由、復盤段

模板欄位可以出現在文章大綱、作者檢查清單或 agent brief 裡。正文要以技術文章方式展開，讓讀者看到推導，作者填表痕跡留在工作流內部。

Backend 技術文章最小模板

Backend 技術文章的最小模板是「概念定位 → 核心判讀 → 判讀訊號 → 風險與邊界 → 交接路由」。這組欄位適合 04 / 06 / 08 這類語言無關的後端能力文章。

 1## 概念定位
 2
 3{概念} 是 {能力 / 流程 / 控制面}，責任是 {它在系統中承擔什麼問題}。
 4
 5這一頁處理的是 {抽象層級}。它跟 {相鄰章節} 的分工是 {邊界}。
 6
 7## 核心判讀
 8
 9判讀 {概念} 時，先看 {第一判準}，再看 {第二判準}。
10
11重點訊號包括：
12
13- {訊號 1}
14- {訊號 2}
15- {訊號 3}
16
17| 判讀面向 | 最小可用判準 | 常見失真 |
18| --- | --- | --- |
19| {面向} | {判準} | {失真} |
20
21## 判讀訊號
22
23- {真實服務中會看到的徵兆}
24- {工程團隊會踩到的操作問題}
25- {事故或演練會暴露的缺口}
26
27## 交接路由
28
29- {上游章節}：{承接內容}
30- {下游章節}：{下一步處理}

這份模板只定義文章最低結構。若某篇文章需要完整案例、方案比較或實作步驟，正文可以增加章節；增加章節時仍要保留責任、判讀、風險與路由。

案例前置欄位

案例前置欄位的責任是讓服務案例能回寫到文章系統。它屬於作者拆案例時的內部欄位，正文只吸收欄位背後的判讀與取捨。

欄位用途例子
來源案例來自事故、演練或公開實踐post-incident review、SRE case
觸發事件如何被發現alert、customer ticket、vendor status
Evidence判讀使用哪些證據log、metric、trace、audit log
Decision當時做了什麼取捨rollback、degradation、containment
Impact影響到誰與什麼功能tenant、region、feature、financial impact
回寫教訓回到哪個章節04.17、6.20、8.19

04 / 06 / 08 的案例拆解可共用這組欄位，但正文仍要用技術文章敘事。欄位幫作者維持可比性，文章幫讀者理解機制。

Agent 共用方式

Claude Code 與 Codex 共用模板時，本文是 blog 內的穩定契約。.claude/ 與 .codex/ 可以引用本文的欄位與判準，但實際模板語意以本文為準。

使用者使用方式
人類作者寫作前確認文章是否需要這組欄位
Claude Code依本文判斷正文與作者模板的分工
Codex依本文建立、補寫與檢查 content 文章
mdtools檢查 Markdown 結構與連結，語意模板交給作者流程

這個安排避免 .claude/ 與 .codex/ 各自演化成不同模板，也避免把 agent 操作細節寫進 backend 讀者正文。

使用邊界

模板適合用在多篇系列文章、跨模組路由與案例回寫。單篇短文、事故紀錄或工具使用筆記可以採較輕的結構，只要仍能說清楚核心責任與下一步。

情境使用方式
Backend 能力章節使用完整最小模板
服務案例拆解使用案例前置欄位，正文呈現案例判讀與取捨
Blog 工具鏈規範依主題調整，保留 posts 的規範與工具鏈定位
Report 原則卡依 report 固有結構，維持 case-driven 原則抽象
Skill reference使用 skill 自身 portable 結構，維持跨專案可移植

模板開始主導正文時，需要降級成作者檢查清單。文章完成後的檢查重點是讀者能否理解技術推導，並確認欄位已在文章背後支撐判讀。

完稿檢查

完稿檢查的責任是確認技術文章維持主線。檢查時先看正文是否能獨立閱讀，再看欄位是否完整支撐交接。

  • 首段是否先說概念責任
  • 判讀訊號是否來自真實服務情境
  • 表格項目是否有延伸說明
  • 交接路由是否指向具體章節
  • 案例欄位是否能回寫到 04 / 06 / 08
  • 正文是否保留技術推導，並把欄位轉成讀者可理解的判讀