↑ 需求首頁 ⌂ 需求中心

FR-047 手冊可讀性/白話化 polish — Session 交接（2026-07-06）

項目 值
角色 不是寫新 spec（47 頁全完成）。是 FR-047 手冊的編輯/潤飾者：user 看 render 出來的 HTML → 指出可讀性/格式問題 → 你 scope 後修
Branch main（全程不切）｜所有 commit 未 push，push 永遠等 user 明示
建議模型 Sonnet（措辭/格式潤飾夠用、省）；遇到要查 code/DB 核事實或業務判斷才切 Opus
Build python3 scripts/deliverables/render_html.py "docs/specs/v1.8.0"（改完必跑，看 ✅）
§1

這個 session 做了什麼（都已 commit）

一連串「讀者導向」的手冊改造，commit 由舊到新：

  • bf3d4775/c3e5c545 側邊欄改領域分組（＝repo 目錄）+ 首頁「產品選單→spec」對照表 + 各群「功能群總覽」子群
  • 0988db03 解除 docs/specs/*/html/ 的 gitignore（HTML 站改入版控，但 html/ 內容還沒 commit，見下）
  • 4657f98c 讀者/生產內容分離：README 只留讀者物、界線規則寫進生產側
  • 13b7d818 8 個 _overview 加「角色是誰」白話介紹 + user story
  • 06368ef5 白話化第一輪：清頁面 spec 內洩漏的生產/內部術語（tracker/FR-047 連結、intro 句的 ui_routes.enable=1 等）
  • 7024218c/fd4a54a8 稽核輪次狀態機圖 + 兩張轉換表白話化（啟動稽核 launch-audit 這種：白話動詞前置、API action 名保留）
  • 06d7cffe 角色速覽提前到 §1（45 頁；§2 開頭那份保留，兩處重複、不改章節編號）
  • 405f7db0/6e4de2f8 §6 API 格式：Request/Response 行內 JSON 全改成 ```json 區塊（22 處/13 檔，6 隻平行 agent + 手動）；欄位註記（必/選填/預設/OneOf）用 JSON5 // 保留

規則都寫進 .claude/skills/writing-feature-specs/（往後新頁自動遵守）：讀者vs生產界線、角色速覽提前§1、API 格式鐵則（json 區塊 + 欄位表別擠散文）。

§2

還沒做（已記在 tracker.md「最後定版前待辦」段，user 拍板留最後一次多 agent 批次做）

  1. 章節連結化 ~1004 處：①表格「詳述」欄裸文字 §N/UC-XX-NN（774 處）②已是連結但只連檔案開頭沒連精確錨點（230 處）。做法：用 build 好的 HTML 反查 pandoc 真實錨點 id（別自己重刻 slugify），每頁一隻 agent 回填 md → 統一 build。
  2. §6 API 格式收尾：Response 散文串只 project-dashboard 有（已修）；Request JSON 已全轉。若還有零星漏網一併掃。
§3

這次驗證有效的工作法（沿用）

user 看 HTML 指問題 → 先 grep 量範圍（別憑感覺）→ pilot 修 1 處給 user 確認方向 → 確認後才批次（獨立的 per-file 工作派平行 agent，prompt 要寫「只改目標、不動其他技術事實、不 spawn agent、不跑 render_html」）→ 收回後主導統一驗證：build ✅ + code-fence 成對 + grep 殘留 0 + 抽讀 2~3 檔忠實度。大改動前先量「跨檔章節號引用」會不會被打斷（曾有 231 處 _overview §N）。

§4

工作區/流程 caveat（重要）

  • 工作區有別的 session 的 WIP，不是你的：docs/specs/v1.8.0/evidence/assets/img/（截圖 session 新圖）、docs/features/FR-046-.../tracker.md（M）、docs/features/ddd-layer-audit/、docs/交付文件/*.docx——commit 前顯式 git add <檔名>、禁 -am/add -A，別把這些掃進來。
  • html/ 已解除 ignore 但內容還沒 commit：等 source md 收斂（含截圖 session）再連 source 一起 commit，避免 build 領先未提交的 md。18M/98 檔，churn 大。
  • FR-046 gate 仍卡著：Task 11 對帳全綠（4449ac8e）等 user 回「對帳 OK」才跑 Task 12/13。非本線工作。
  • 收尾類（SUMMARY/memory/Notion/歸檔）一律等 user 明令，不自動做。
§5

座標

  • 主戰情：docs/features/FR-047-2607-feature-spec-handbook/tracker.md（含「最後定版前待辦」段）
  • SOP/規則：.claude/skills/writing-feature-specs/（SKILL.md + references/page-spec-template.md）
  • 事實 dump：scripts/deliverables/out/{db_schema,routes}.json
  • 合格範本：docs/specs/v1.8.0/project-management/project-planning.md