Analyze Definition

[!IMPORTANT] 前提條件: 執行此技能前，請先執行 @startup-check 並確認既有的技能結構（@help）。 這可避免遺漏已定義的開發流程。

分析範圍的限定（必須）

[!CAUTION] 請勿分析工作區外的專案

務必確認 AI 編輯器提供的「工作區定義」，僅分析已定義的專案。

確認步驟

1. 確認工作區定義: 讀取使用者的 user_information 或 IDE 的工作區設定
2. 取出已定義路徑: 從 URI 列表找出分析對象目錄
3. 排除範圍外: 執行 find 或 grep 時僅針對定義的路徑

範例: 正確的分析對象

✅ 已定義（分析對象）:
- uppmag.com/.../themes/sonobuoy/
- uppmag.com/.../themes/sonobuoy-uppmag/
- sso/html/
- twst-exhibition/

❌ 未定義（分析對象外）:
- sonobuoy-coding/  ← 別的專案
- laravel-*/        ← 別的專案

禁止事項

• ❌ 遞迴搜尋 /Users/.../sonobuoy/ 整體
• ❌ 未確認工作區定義即執行 find
• ❌ 將發現的所有 CLAUDE.md 皆列為分析對象

分析原則

🚨 結論的使用根據義務（最重要・全項目共通）

[!CAUTION] 所有「不足」「建議改善」的判定，都必須引用 grep 驗證結果

嚴禁無根據的判定。此原則適用於測試、Workflows、OpenSpec 等所有項目。

判定前的必須動作

在判定為「❌ 未記載」「⚠️ 建議新增規則」之前，務必執行以下動作：

1. 使用 grep 搜尋中央 AGENTS.md（sonobuoy-cms）

   grep -n "搜尋關鍵字" sonobuoy-cms/AGENTS.md
   

2. 使用 grep 搜尋個別專案的 AGENTS.md

   grep -n "搜尋關鍵字" 對象專案/AGENTS.md
   

3. 在報告中引用搜尋結果

   項目X: ✅ 正常
   - 根據: sonobuoy-cms/AGENTS.md:行號 確認已有「記載內容」
   
   項目Y: ❌ 未記載
   - 根據: grep 搜尋確認中央・個別皆無相關內容
   

禁止模式

[!WARNING] 以下模式會導致誤判，嚴格禁止

❌ 用 view_file 看過內容，但未做 grep 驗證就判定「未記載」 ❌ 僅確認個別 AGENTS.md，未確認中央 AGENTS.md 就下判定 ❌ 建立了改善提案，但未在報告中引用根據 ❌ 用「大概沒有寫吧」的推測來判定

報告格式（必須）

所有的分析報告中，各項判定皆需明記根據：

| 項目 | 判定 | 根據 |
|------|------|------|
| 測試 | ✅ 正常 | AGENTS.md:199「母主題 \| npm run test:e2e」 |
| Workflows | ✅ 正常 | AGENTS.md:228-231 多專案操作表 |
| OpenSpec | ✅ 正常 | 行1-18 OPENSPEC 區塊存在 |

二層分析（必須）

所有分析皆需進行以下二層確認：

差異分析

分析結果請依以下格式報告：

必須步驟

1. 專案基盤確認（最優先）

在分析 AI 規則前，務必確認以下項目：

測試基盤

• find . -name "phpunit.xml" -o -name "phpunit.xml.dist" 確認設定
• ls tests/ 或 ls test/ 確認測試目錄
• find . -name "*Test.php" | head -20 確認實際測試檔案
• 確認 Playwright/Cypress 等 E2E 測試有無

[!WARNING] 二層分析強制檢查

在判斷「測試未設定」前，務必確認兩者：

層級	確認對象	指令範例
AI 規則層	AGENTS.md 的測試章節	view_file AGENTS.md
實作層	package.json / composer.json	view_file package.json
實作層	playwright.config.ts / phpunit.xml	find . -name "playwright.config*"

禁止僅確認其中一方就判斷「不足」。

CI/CD 基盤

• 確認 .github/workflows/ 有無
• 確認 .gitlab-ci.yml 有無
• 確認部署腳本（deploy.sh 等）有無

依賴關係

• 確認 composer.json / package.json 的 scripts 章節
• 確認測試執行指令（npm test, composer test 等）
• 各專案務必 view_file package.json（即使 AGENTS.md 無記載）

2. 專案性質確認

• 確認各專案類型（前端/後端/Full Stack）
• 透過 find . -name "*.css" 或 resources/views/ 確認是否有前端
• 純後端專案不需要 CSS 規範

3. 驗證實際程式碼使用

• 不只看文件，需用 grep 確認實際程式碼
• 例: SSO 整合確認 → grep -r "sso\|SSO\|api.uppmag" --include="*.php"
• 例: 功能旗標使用 → grep -r "SONOBUOY_FEATURES" --include="*.php"

4. 確認既有的自動化機制

• 確認 .agent/workflows/ 的既有工作流程
• 判斷「不足」前，先確認是否已有既有機制對應

5. 結論驗證

• 針對判斷為「有問題」的項目，再次確認是否真的有問題
• 考慮專案性質，排除「不需要」的情況
• 製作二層分析的差異表並報告

禁止事項

• ❌ 僅看 AI 規則檔就下結論
• ❌ 未確認專案實際目錄結構就判斷「不足」
• ❌ 未進行二層分析就報告
• ❌ 僅做文件表面比對就下結論
• ❌ 未考慮專案性質就機械式比較
• ❌ 未確認既有自動化機制就判斷「不足」

已知結構（防止誤判）

[!IMPORTANT] 以下結構為設計上的意圖，請勿誤判為「不足」或「重複」。

AGENTS.md 配置規則

注意: 子專案若無 AGENTS.md 是正常的。

AI 工具設定目錄

注意: 子專案若無 .claude/ 或 .opencode/ 是正常的。

子主題 workflows 規則

注意: 子主題繼承母主題，故不需要獨立的 deploy.md 或 run-tests.md。

測試規範的記載

[!CAUTION] 子主題的測試指令由中央 AGENTS.md 統一管理

務必確認 sonobuoy-cms/AGENTS.md 是否有以下記載：

| 子主題 | `npm run test:e2e` |

若有此記載，即使個別子主題 AGENTS.md 無記載也判定為正常。

注意: 若測試執行方法已記載於 sonobuoy-cms/AGENTS.md 或 package.json，不需在個別 AGENTS.md 重複記載。

主題測試分析的必須步驟（母主題・子主題共通）

[!CAUTION] 在判定「測試未記載」前，務必執行以下驗證

嚴禁省略此步驟導致誤判。

分析時務必依照以下順序確認：

1. 用 grep 確認中央 AGENTS.md 的統一表（最優先・必須）

   grep -n "親テーマ\|子テーマ" sonobuoy-cms/AGENTS.md | grep "test"
   

2. 目視確認表格內容 確認 sonobuoy-cms/AGENTS.md 的「測試執行指令」表是否有：

   • | SSO | npm run test:all |
   • | 親テーマ | npm run test:e2e |（母主題）
   • | 子テーマ | npm run test:e2e |（子主題）

3. 確認 package.json 各專案是否有 npm run test:e2e script

判定規則：若上述 1 或 2 在中央 AGENTS.md 有記載，即使個別 AGENTS.md 無記載也是正常。

[!WARNING] 常見誤判模式（禁止）

❌ 只看個別 AGENTS.md 就判斷「測試指令未記載」 ❌ 未確認中央 AGENTS.md 的統一表就提案「建議新增規則」 ❌ 無 grep 驗證就建立改善提案

務必在報告引用 grep 結果：

母主題測試: ✅ 正常
- 根據: sonobuoy-cms/AGENTS.md:199 已記載「| 親テーマ | npm run test:e2e |」

子主題 E2E 測試配置規則

所有子主題（sonobuoy-uppmag、sonobuoy-child）皆存在 playwright.config.ts 與 package.json：

注意: 兩個子主題皆有測試基盤。即使個別 AGENTS.md 無指令記載，因中央 sonobuoy-cms/AGENTS.md 已統一管理，故為正常。

Workflows 分析的必須步驟

[!CAUTION] 在判定「Workflows 未記載」前，務必執行以下驗證

Workflows 的記載位置：

各專案的 AGENTS.md 有「多專案操作」章節，包含工作流程指令表。

grep 驗證指令：

# 確認 Workflows 記載
grep -n "/code-review\|/backlog\|/slack\|/deploy" 對象專案/AGENTS.md

應確認的記載內容：

判定規則：

• 若中央或個別 AGENTS.md 有記載上述指令則為正常
• 即使 .agent/workflows/ 有檔案存在，只要 AGENTS.md 有記載就不判定為「未記載」

OpenSpec 目錄結構

sonobuoy-cms/openspec/specs/ 為空是預期的動作。

各專案維護獨自的 specs：

• 母主題: themes/sonobuoy/openspec/specs/
• SSO: sso/html/openspec/specs/
• 子主題: themes/sonobuoy-child/openspec/specs/

WP Root 的 openspec/ 目錄

注意: WP Root 僅管理 wp-config.php 與 .htaccess，但為與其他專案保持一致性，完整保留了 openspec/（含 changes/、specs/）。此為設計意圖，請勿報告「冗餘」或「建議整理」。