vlv-code/init-meta-project

Agent 環境初始化與升級（Meta-Project Init & Audit）

用於為任何儲存庫準備 Agent 工作流程的自動化技能。會自動檢查是否已存在 meta-project 結構，避免覆蓋已累積的資料，並執行安全升級至最新標準，或從頭建立全新的結構。

此技能建立在「連續/機會性重新整理」原則之上：當存取知識切片時，Agent 必須填補缺口，並維持對專案的整體願景。

---

何時使用此技能

• 使用者要求：「為 Agent 準備儲存庫」、「初始化 meta-project」、「檢查 agents.md」、「更新 Agent 結構」、「重新整理 meta-knowledge」。

---

執行步驟

階段 0：檢查現有 Meta-Project 環境

在執行任何寫入操作前，檢查 meta-project 元件是否存在：

1. 檢查儲存庫根目錄是否存在 AGENTS.md。
2. 檢查是否存在 .agents/project_knowledge/ 和 .agents/skills/ 目錄。

情境 A：結構已存在（稽核與安全升級模式）

如果儲存庫中已有 AGENTS.md 或 .agents/ 資料夾：

1. 禁止破壞性覆寫：
   • 嚴格禁止刪除或覆寫 observations.md——所有累積的觀察記錄必須保留。
   • 禁止刪除現有 AGENTS.md 中的自訂不變量和使用者描述。
2. 合規性稽核：
   • 檢查 AGENTS.md 是否包含「原則與架構方向（北極星）」章節。如果缺少，請新增它，但不修改服務目的和不變量。
   • 檢查 AGENTS.md 中是否包含帶有「存取 + 機會性重新整理」連結的指令協定。如果過期，請更新該章節。
   • 檢查 boundaries.md 是否有 glob 模式使用、資料目錄保護（data/**、*.db）、將格式化/渲染模組分配給黃區，以及是否存在 Default Deny（黑區）不變量。
   • 檢查 observations.md 表格是否有 Category 欄位。如果使用舊的 4 欄格式，請更新表格標題，但不要刪除資料列。
   • 驗證 .agents/skills/ 中 SKILL.md 檔案（record-observation、sync-architecture、ground-meta-project）的新鮮度。
3. 安全增強：
   • 建立遺失的切片（例如，如果缺少 weak_spots.md）。
   • 在 AGENTS.md 的技能註冊表中補充新的專業技術棧技能。
4. 升級報告：
   • 通知使用者：「偵測到現有 meta-project。已稽核並升級至最新標準，未遺失任何累積資料。」

---

情境 B：初始設定（乾淨 Scaffold 模式）

如果沒有任何結構，請執行標準的兩階段演算法：

第一遍：快速掃描與骨架產生（快速且高層級）

1. 快速檢查儲存庫根目錄： 列出根目錄並識別：

   • 清單檔案：package.json、pyproject.toml、go.mod、Cargo.toml、requirements.txt、pom.xml、docker-compose.yml。
   • 核心目錄：src/、app/、tests/、migrations/、scripts/、data/。
   • 零未對應目錄規則： 列舉儲存庫根目錄中的所有頂層原始碼目錄。嚴格過濾掉 .gitignore 路徑、VCS 中繼資料以及標準建置/套件/測試快取（.git、node_modules、.venv、venv、dist、build、coverage、__pycache__、.pytest_cache、.idea、.vscode）。每個剩餘的頂層原始碼目錄都必須明確被記錄並對應到 boundaries.md 中的綠區、黃區或紅區（未對應的目錄預設歸入 Default Deny / 紅區）。
   • 從 README.md（如果存在）取得專案名稱、目的和核心概念。
   • 從 .env.example（如果存在）取得必要的金鑰和依賴項。

2. 識別技術棧和核心原則：

   • 制定一個簡潔的技術棧字串（例如：Python 3.12、FastAPI、uv、pytest、Docker）。
   • 突出顯示 2-3 個基線方向（例如：架構簡單性、嚴格型別、資料不可變性、離線優先）。

3. 建立目錄結構： 建立目錄：

   • .agents/project_knowledge/
   • .agents/project_knowledge/archive/
   • .agents/skills/record-observation/
   • .agents/skills/sync-architecture/
   • .agents/skills/ground-meta-project/
   • scripts/

4. 部署內建的 meta-project 技能和執行時期腳本： 將以下嵌入的範本中的 SKILL.md 檔案寫入：

   • .agents/skills/record-observation/SKILL.md
   • .agents/skills/sync-architecture/SKILL.md
   • .agents/skills/ground-meta-project/SKILL.md 將零依賴的邊界與壓縮自動化腳本部署到儲存庫的 scripts/：
   • scripts/check_boundaries.py（邊界閘道 CLI）
   • scripts/compact_memory.py（Context Rot Shield 與記憶體壓縮器）

5. 建立初始知識切片草稿： 在 .agents/project_knowledge/ 中寫入檔案：

   • observations.md（5 欄表格，包含第一行初始化記錄；使用跨平台指令範例，例如：python -m pytest）。
   • boundaries.md（區域範本，包含基本 glob 模式：格式化在黃區，資料在紅區）。
   • weak_spots.md（基線風險註冊表結構）。
   • architecture.md（基線架構支架）。
   • tasks.md（活躍目標、團隊檢查清單和委派註冊表）。

第二遍：儲存庫深度探索、原則與 Shell 技能

1. 強制核心檢查清單： 禁止在未讀取關鍵模組的原始碼的情況下，使用樣板範本填充 weak_spots.md 和 architecture.md！ Agent 必須針對以下關鍵領域執行 read_file 呼叫：

   • 儲存與資料庫： 讀取主要資料存取模組（storage.py、儲存庫、模型）。評估單體大小（LOC 數量）、結構耦合和遷移設定。
   • 外部 API 與服務客戶端： 讀取整合模組（AI 模型 SDK、外部客戶端）。檢查重試、逾時、備援和全域單例。
   • 容器化與執行時期： 讀取 Dockerfile、docker-compose.yml 和 CI 工作流程（.github/workflows/）。檢查系統二進位依賴項（FFmpeg、工具）、使用者權限（UID）和資料磁碟區掛載。
   • 使用者介面與輸入： 讀取鍵盤/路由器模組。檢查平台限制（例如：Telegram callback_data 的 64 位元組限制、FSM 狀態、破壞性動作的確認）。

2. 互動式校準訪談（編碼化的雙問題協定）： 自動掃描可以識別程式碼中存在什麼，但無法偵測未記錄的歷史背景、業務不變量或生產環境敏感性。Agent 透過簡短、結構化的互動式訪談（使用 ask_question 工具或直接互動提示）詢問正好 2 個重點問題：

   • 問題 1（北極星與核心不變量）： 「哪些核心的架構不變量、業務規則和生產環境限制（North Stars）在任何修改時都絕不能違反？」
   • 問題 2（紅區與敏感路徑）： 「哪些特定的目錄或模組（計費、資料庫、加密、金鑰、遺留程式碼）是關鍵的，必須嚴格地放入紅區？」

   處理答案：

   • 使用者對問題 1 的回答會立即整合到 AGENTS.md 的第 1 節（「原則與架構方向（北極星）」）。
   • 使用者對問題 2 的回答會在單次 flush 之前對應到 boundaries.md 的紅區。
   • 如果使用者略過或提供空回應，則優雅地回退到從核心檢查清單中推斷出的方向。

3. 校準專案概念與原則： 綜合檢查清單的發現和訪談答案，形成 2-3 個簡潔的架構方向（North Stars），防止 Agent 產生矛盾的動作。

4. 從 Agent Shell 註冊表匹配技術棧技能： 將儲存庫技術棧對應到 Agent 環境（~/.gemini/config/skills/ 和內建）中可用的專門技能：

   • Python / uv / ruff → python-pro
   • FastAPI → fastapi-pro
   • TypeScript / JavaScript → typescript-expert
   • Next.js → nextjs-best-practices
   • Docker / Dockerfile / Compose → docker-expert
   • PostgreSQL / SQL / migrations → postgresql-optimization、sql-pro
   • Kubernetes / Helm → kubernetes-architect
   • Telegram bot / aiogram → telegram-bot-builder
   • CI/CD pipelines → github-actions-creator
   • Clean code & review → clean-code、code-reviewer

5. 校準邊界（boundaries.md）： 為實際的專案目錄精煉 .agents/project_knowledge/boundaries.md 中的 glob 模式：

   • Default Deny / 100% 路徑覆蓋（零未對應目錄）： 保證每個未被忽略的頂層原始碼目錄都被明確分配到某個區域。添加 Default Deny（黑區）規則：任何未對應的路徑預設為嚴格的紅區。
   • 測試區域區分：
     • 為新功能建立新測試——綠區。
     • 現有的回歸測試套件（tests/**、*_test.*、*.spec.*）——嚴格的黃區，並帶有禁止削弱斷言（assert/expect）的不變量。
     • 架構完整性、API 合約和資料結構測試（*integrity*、*contract*、*schema*、E2E）——嚴格的紅區。
   • 格式化/跳脫模組和範本引擎——嚴格的黃區。
   • 資料庫檔案和目錄（data/**、*.db、*.sqlite*）——嚴格的紅區。
   • 用實際的遷移路徑（alembic/versions/**、prisma/migrations/** 等）取代佔位路徑。
   • 用實際的子系統位置取代路由/控制器路徑。

6. 風險與弱點分析（weak_spots.md）： 記錄在核心檢查期間識別的具體技術債務（單體、單例）、外部執行時期依賴項（Redis、Postgres、訊息代理、系統工具如 FFmpeg）、平台限制以及來自 .env.example 的強制變數。

7. 填入架構切片（architecture.md）： 根據檢查的核心模組描述高層級技術棧、子系統、背景任務/排程器和資料流。

   • 條件式端到端資料流： 每當偵測到多層級、客戶端-伺服器、API 或 UI 元件時，產生「端到端資料流（飛行前流程追蹤）」架構（對應 [來源：UI/CLI/事件] ➔ [傳輸：API 路由 / 訊息] ➔ [領域 / 儲存：持久化] ➔ [組合 / 打包器] ➔ [消費者：客戶端 / 守護行程]）。對於沒有外部通訊或持久化層的純單層 CLI 或 stdlib 函式庫，則省略此部分以避免上下文膨脹。

8. 記憶體內合成 Flush 協定： Agent 不會將中間草稿寫入磁碟。所有不變量都在第一遍和第二遍期間於工作記憶體中合成，之後檔案會以嚴格的由下而上順序寫入：

   • 步驟 A：預先安裝的技能（.agents/skills/record-observation/、sync-architecture/、ground-meta-project/）與自動化腳本（scripts/check_boundaries.py、scripts/compact_memory.py，如果是共享儲存庫設定）。
   • 步驟 B：知識切片（observations.md -> boundaries.md -> weak_spots.md -> architecture.md）。
   • 步驟 C：根目錄護照（AGENTS.md）——嚴格地放在最後，作為切片和技術棧技能的參考匯總器。

---

最終化與驗證

1. 使用 Get-ChildItem -Recurse .agents 或 ls -R .agents 驗證已建立/更新的檔案。
2. 本地隱形覆蓋選項： 如果在外部/客戶端專案中初始化，或使用者要求不提交 Git 的個人模式：
   • 將 AGENTS.md 和 .agents/ 加入到目標儲存庫的 .git/info/exclude 中。
   • 驗證 git status：meta-project 檔案不得出現在 Untracked files 中。
3. 向使用者輸出簡潔摘要：
   • 執行模式（初始設定 vs. 含升級的稽核；共享 vs. 隱形覆蓋）。
   • 已建立/更新的檔案樹。
   • 捕獲的專案方向（North Stars）。
   • 連結的技術棧技能清單。

---

嵌入的參考範本

範本：record-observation/SKILL.md

---
name: record-observation
description: >-
  使用此技能將未記錄的錯誤、環境異常、執行時期邊緣案例或非顯而易見的解決方案記錄到儲存庫的 `.agents/project_knowledge/observations.md` 表格中。
---

# 在儲存庫知識庫中記錄觀察

1. 確認 `.agents/project_knowledge/observations.md` 存在。
2. 檢查最後 20 列是否存在重複項。
3. 將條目嚴格附加為單一 Markdown 表格行：
   `| YYYY-MM-DD | [<category>] | <Path_or_component> | <Brief issue summary/fact> | <Solution or workaround> |`
   類別：`[build]`、`[runtime]`、`[deps]`、`[db]`、`[api]`、`[test]`、`[env]`、`[ci]`、`[boundaries]`、`[orchestration]`、`[decommission]`、`[incident]`、`[init]`，或明確的領域標籤（例如 `[theme]`）。
4. 如果記錄行數 > 30-40，將已解決的記錄封存到 `.agents/project_knowledge/archive/observations-YYYY.md`。

範本：sync-architecture/SKILL.md

---
name: sync-architecture
description: >-
  使用此技能分析儲存庫模組、依賴項和進入點，並產生或更新 `.agents/project_knowledge/architecture.md`。
---

# 同步專案架構切片

1. 讀取依賴項和建置清單。
2. 識別進入點和頂層目錄。
3. 識別 3-5 個子系統、它們的角色和資料流。
4. 更新 `.agents/project_knowledge/architecture.md`。
5. 向使用者顯示變更的簡短摘要。

範本：ground-meta-project/SKILL.md

---
name: ground-meta-project
description: >-
  緊急接地與重新校準技能：停止失控的編輯，強制拉遠視角，重新讀取 AGENTS.md、
  活躍角色護照、boundaries.md 和架構圖，診斷上下文漂移，並重置年代...

…