hellices/flow-atlas

flow-atlas 是做什麼的？

儲存庫本身的 AGENTS.md、設計文件和治理規則優先於此技能。

三個部分

atlas 會產生程式碼所確定的事實。你則編寫需要意圖的內容，而 atlas 會檢查你所寫的。在這兩者之間，你需要解釋哪些工作屬於哪個元件，並依據 references/boundaries.md 中的標準。你所做的每一個決定都必須放入 atlas 會讀取的檔案（流程檔案、例外檔案、設定檔、回饋），這樣下一次執行和下一個代理才能看到。

atlas 產生：切勿手寫這些

事實	命令
surfaces、calls、edges、operationIds、registries、contract 版本	scan
依路徑、方法或元件的 surfaces 和 calls	query
某個 surface 的上游呼叫者及下游服務	trace
Flow 草稿：名稱、沿程式碼路徑的步驟、當一個元件呼叫它時的進入點、分支的候選點	draft flow
Flow 是否在程式碼中成立，以及其作者欄位是否已填寫	flows（條件）
包含位置與鄰近路徑的發現	check、explain
版本之間的變更	diff
設定候選項目以及設定涵蓋程度	inventory、scan
每個元件的 OpenAPI 描述、已提交的描述與程式碼的一致程度，以及當程式碼決定時哪個描述才是元件真正的描述	scan、inventory

不要手動 grep graph.json、從文字搜尋猜測呼叫者，或憑記憶輸入 surface ID：請從 atlas 輸出中複製。

你編寫：atlas 檢查它

項目	檢查方式
Flow 的 title 和每個步驟的 role	Documented
owner、labels、sources、lifecycle（當步驟尚未建置時設為 planned）	schema；Resolved 會將 planned 步驟分開計算
當你已編寫流程的意圖後，加上 generated: { by: <工具>/<模型>, at }；stale_after 用於設定應複審的時間（OKF）	schema；Fresh
當多個元件呼叫第一個步驟時的進入元件；處理器分支的下一個步驟	EntryCalled、Connected
produces	ProducesListed
例外：原因、decidedBy、reviewBy	過期會讓該發現重新出現
誤報，附上原因	stats
設定	scan 涵蓋率
針對 atlas 無法解析的元件，其框架產生的 OpenAPI 文件（routes[].openapi、references/openapi.md）	scan 涵蓋率及 limit: 行
origins：從部署檔案中取得每個元件在環境中執行的基礎 URL	export arazzo 會註記缺少的項目
當 atlas 報告某個元件的描述 ambiguous 時，設定 openapi.<component>	export arazzo 會拒絕，直到設定完成

不要把你的部分交給工具：沒有合理原因（人能接受的原因）就不要更新 publicSurfaces、例外或基準線。切勿編寫帶有 human: 角色的 verified 條目：這記錄的是人的複審，而流程的信任等級（unverified、machine-confirmed、human-reviewed）取決於此。

你解釋：邊界

一個跳躍是否屬於它所在的元件；一個相似的 surface 是否已經完成相同工作；一個落差是缺陷、計畫還是誤報；應該信任一個 edge 到何種程度；以及流程從哪裡開始到哪裡結束。請遵循 references/boundaries.md；它會排列來源的順序（儲存庫規則優先，然後是流程角色，最後是程式碼）並給出判斷標準。

設定

• 執行 atlas --help。如果 atlas 未安裝，請透過 npx 執行它（npx github:hellices/flow-atlas --help）或請使用者安裝；不要手動重新實作它的讀取功能。
• 設定檔為 <root>/atlas.config.yaml、<out>/atlas.config.yaml 或 --config <檔案>。如果沒有，請遵循下方的「設定中」步驟。
• 如果儲存庫不可寫入，請傳入 --out <外部目錄>。所有寫入都會到該目錄。

設計變更

1. 執行 atlas query --path <路徑或片段> 和 atlas query --component <名稱> 以查看已存在的內容。
2. 執行 atlas trace <最近的 surface> 以查看鏈：客戶端呼叫、BFF 路由、其處理器達到的 port 方法、每個方法匹配的服務路由。
3. 決定：重複使用、擴充或新增。記下你將要新增或更改的 surface 鍵，以及每個跳躍屬於哪個元件。如果兩個元件最終會執行相同的步驟，請在編寫程式碼之前解決這個問題。
4. 如果儲存庫維護流程（flows/*.flow.yaml），請更新 Flow，或使用 atlas draft flow <surface> 開始一個新的 Flow（請參閱「編寫流程」）。將尚不存在的步驟標記為 lifecycle: planned。

在實作期間

在新增路由或客戶端呼叫後，執行 atlas trace <surface>。上游應顯示你預期的呼叫者，下游應顯示你預期的呼叫。空的一邊表示尚未接通，或者以工具無法讀取的方式接通（例如在遠離呼叫處建構的路徑、以另一種語言編寫的處理器）；請開啟程式碼並說明是哪一種情況。

當你新增、移除或更改某個元件的路由，且該元件的路由來自產生的 OpenAPI 文件時，請在同一次變更中重新產生該文件。僅客戶端呼叫本身不會更改文件。

編寫流程

1. atlas draft flow <第一個 surface> 會印出一個包含程式碼所確定的一切的 Flow；加上 --to <surface> 可跟隨程式碼到達給定的終點。將其儲存在 flows/<名稱>.flow.yaml（如果儲存庫不可更改則儲存在 <out>/flows/）。
2. 填寫每個 agent: 註解：title、每個步驟的 role（該元件做什麼以及留給其他元件做什麼）、owner、lifecycle、produces；選擇進入點以及草稿列出候選點的下一個步驟。保留沒有標記的值；它們來自程式碼。
3. 執行 atlas flows，直到流程的 Ready=True。如果 Resolved、Connected 或 EntryCalled 為 False，表示程式碼或流程有誤：請根據 references/boundaries.md 決定是哪個。如果 Documented 為 False，表示某個作者欄位為空。

一個檔案可以包含多個以 --- 分隔的流程。Surface ID 應使用 OpenAPI 範本（{id}）編寫路徑參數。請勿將位置、邊緣或條件複製到檔案中；atlas 每次執行時會自行計算。格式為 flow-atlas 套件中的 schema/flow.schema.json，其 docs/schema.md 和 docs/responsibilities.md 有詳細說明。

完成前

1. 執行 atlas check --since <起始修訂版本>。只會顯示你的變更引入的發現。
2. 針對每個發現：執行 atlas explain <鍵> 會顯示位置和相似的路徑。然後修復它，或記錄一個例外，或記錄一個誤報。請參閱「處理發現」。
3. 在 PR 描述或交接備註中放入 atlas diff <基底>..WORKTREE --format markdown（或 <基底>..HEAD）以及每個新 surface 的 trace。

當設定落後時

徵兆：stderr 上出現 limit: 行（設定的檔案沒有匹配任何內容，某個來源產生的結果不到基準線的一半），或你確信被呼叫的路徑出現 FA001。執行 atlas inventory，與設定進行比較，修正它（references/config.md），然後再次檢查 atlas scan 涵蓋率。在執行 atlas baseline update 之前先請教他人。

設定中

atlas inventory 會列出候選項目而不做出任何決定。根據它編寫設定（references/config.md）；對於 atlas 無法解析的伺服器框架（Spring、Django、Flask 等），請產生其 OpenAPI 文件並將路由指向它（references/openapi.md），執行 atlas scan 直到每個來源都產生你預期的結果，執行 atlas check，然後與他人一起審查一部分發現。只有到那時才記錄基準線。

處理發現

首先決定它是缺陷、計畫還是誤報（references/boundaries.md），然後：

• 如果發現就是錯誤，請修復它：接通遺漏的呼叫者、移除無效的路由、新增生產者、將呼叫指向正確的路徑。references/rules.md 列出了每條規則的常見原因。

• 當程式碼是故意正確時，請新增一個命名該決定的例外：

  # flows/atlas-exceptions.yaml（或 <out>/exceptions.yaml）
  - rule: FA001
    key: FA001|orders|GET /orders/{id}/history
    reason: 服務先出貨；應用程式畫面在下一個版本中跟進。
    decidedBy: docs/orders.md#history
    reviewBy: 2026-12-31
  

  提供給儲存庫外部客戶端的 surfaces 應放入設定中的 publicSurfaces。

• 當發現是錯誤的：atlas feedback <鍵> false-positive --note "<原因>"。如果萃取器誤讀了某個檔案，請說明是哪個檔案以及如何誤讀。

除非有人要求，否則切勿執行 atlas baseline update。切勿為了滿足發現而編輯產生的程式碼。

機器可讀輸出

--format json 或 --format yaml 會列印遵循 flow-atlas 套件中 schema/*.schema.json 的文件，每個文件都包含 apiVersion、kind 和 provenance（提交和讀取的檔案，包含摘要）。請讀取這些而非解析文字輸出；請根據條件的 reason 進行分支，而不是其 message。atlas check --format sarif 會將發現以 SARIF 2.1.0 格式輸出，用於程式碼掃描和 IDE 檢視器；atlas export arazzo 會將流程以 Arazzo 1.0 格式輸出，用於 API 工作流程和端到端工具，這些工具仍需要填入參數、請求主體和成功條件。

讀取輸出

• 發現狀態：new 是你的；baseline 是已接受的技術債；excepted 已被涵蓋；expired-exception 需要人處理。
• 在 trace 中，= 透過方法和路徑將呼叫連接到 surface；~ 將路由連接到其處理器執行的對外呼叫：寫在處理器自己的程式碼或其呼叫的函式中（證據 static），或包含在處理器呼叫的名稱的方法中（證據 name），對於 Spring 頁面，則由其檢視名稱渲染的模板製作（via view <名稱>）。透過通用名稱（get、send）的 ~ 需要查看程式碼。
• 呼叫的 in <名稱> 是包含該字串的函式。錯誤標籤或日誌訊息中的字串，即使看起來像路徑，也不是請求；範圍通常會顯示這一點。
• 只會讀取已設定的檔案，並且只讀取其中確定寫入的內容：文字路徑，具有標準或框架賦予的意義。來自變數、其他模板引擎或 htmx 與 Vue 屬性的 URL 不會被讀取，也不會被猜測。因此，「沒有呼叫者」表示 atlas 無法讀取；在移除任何東西之前請檢查程式碼，並將提供給儲存庫外部客戶端的 surfaces 宣告在 publicSurfaces 中。沒有發現並不證明流程是完整的。

參考資料

• 解釋邊界、決定缺陷、計畫或誤報：references/boundaries.md
• 規則、原因、解決方案、何時適用例外：references/rules.md
• 編寫或修正設定：references/config.md
• 從框架產生的 OpenAPI 文件中讀取路由，以及如何產生它：references/openapi.md