Codebase Trellis
結構化、支援並安全地整合 AI 輔助的程式碼變更。
生態系統：
codebase-orient：理解程式碼庫。codebase-visualize：繪製程式碼庫地圖。codebase-trellis：支援安全的變更成長與整合。
何時使用此技能
使用此技能的時機
- 檔案已變更，需要安全地暫存、規劃提交或執行提交。
- 需要設定、完成或清理分支或工作樹。
- 需要檢查或準備推送、PR 或 CI 狀態。
- 需要稽核 Git/GitHub 儲存庫的狀況。
- 長時執行的代理工作階段在繼續前，需要進行結構化的狀態審查。
- 工作目錄髒亂，且下一步的最佳行動不明確。
跳過此技能的時機
- 任務是微小的單一檔案、已知的修復，且沒有 Git 狀態的不確定性。
- 正在進行唯讀探索，且沒有提交/推送/清理的計畫。
- 剛剛才呼叫過其他技能（
codebase-orient、codebase-visualize），且後續沒有 Git 相關工作。
簡單 vs 結構化分類
在執行任何工作流程前，先對每次呼叫進行分類。
簡單通行：
- 局部錯誤修復
- 僅文件或僅複製的變更
- 依賴項升級
- 小型重構
- 僅測試的變更
- 已界定範圍的提交準備
結構化通行：
- 廣泛的多檔案變更
- 多個套件
- 同時包含 UI、API 和測試
- 遷移或產生的檔案
- 長時間運行的代理工作
- 預計會有多個提交
- 可能需要繼續或交接
如果不確定，預設為簡單通行。若檢查後發現實際工作比預期更大，可升級為結構化通行。但一旦建立安全狀態後，就不得降級為簡單通行。
強制層級
Trellis 在一個 4 層安全模型中運作。這些層級並非等效，且任何層級都不能取代其他層級。
第 1 層：技能紀律（核心 v1 層）
技能會檢查、回報並阻擋危險操作。在任何正常的 Git 儲存庫中都能運作，無需額外的掛鉤或 GitHub 存取權限。這是行為層面——取決於代理是否遵循技能指示。
第 2 層：本地 Git 掛鉤
儲存庫本地的掛鉤可以在提交或推送時執行。Trellis 可能會建議掛鉤，但在 v1 中不要求也不安裝它們。掛鉤可能遺失、可以透過 --no-verify 繞過，或無法在不同複製之間共享。
第 3 層：Claude Code 掛鉤
主機層級的掛鉤可以圍繞工具使用、檔案變更和權限進行操作。僅供選擇性強化——並非獨立核心的必要條件。不要假設它們已安裝。
第 4 層：GitHub 保護措施
GitHub 端的強制執行：分支保護、規則集、必要檢查、必要審核、簽署提交、強制推送限制、合併佇列、秘密掃描、程式碼掃描、Dependabot。當 API 存取許可時進行檢查和回報；永遠不要假設保護措施存在。
非等效規則：
- 技能紀律不是掛鉤。
- 本地掛鉤不是 GitHub 分支保護。
- 通過的本地 grep 不是秘密掃描。
- PR-head 檢查不是合併佇列檢查。
- 可見的綠色勾選標記並非證明所有必要檢查已通過相關的 SHA。
如果某個層級不可用或無法驗證，請直接說明。
互通性邊界
獨立核心
Codebase Trellis 必須在任何正常的 Git 儲存庫中運作，無需依賴姊妹技能的成品。它擁有：
- Git 狀態和髒狀態檢查
- 已暫存、未暫存、未追蹤、忽略、已產生、敏感和預先存在的變更偵測
- 提交分組和提交計畫交接
- 分支/工作樹安全性
- 推送/PR/CI 閘門
- 清理規則
- Trellis 報告輸出
選擇性建議讀取
如果存在姊妹技能的成品，Trellis 可以將它們讀取為僅供參考的建議上下文。
來自 codebase-orient（範例：docs/ai/CODEBASE_MAP.md、docs/ai/CHANGE_SURFACES.md、docs/ai/OPEN_QUESTIONS.md）：
- 儲存庫佈局和套件/工作區結構
- 已知檢查和產生文件政策
- 重要的慣例和危險區域
來自 codebase-visualize（範例：docs/ai/visualize/codebase-graph.json）：
- 影響範圍和受影響的模組
- 文件到程式碼的邊緣和高中心性檔案
規則：
- 不要求這些檔案存在。
- 不要重新產生它們。
- 不要無聲無息地修改它們。
- 不要因為缺少視覺化圖而阻塞常規的提交規劃。
- 不要將它們視為比原始碼/設定/規範文件更具權威性。
交接觸發條件
- 當儲存庫結構不明確、已知檢查未知，或代理缺乏足夠上下文來分類風險時，建議使用
/codebase-orient。 - 當變更影響廣泛或涉及架構性變更、依賴關係很重要，或影響範圍能改善決策時，建議使用
/codebase-visualize。
通用規則
始終：
- 從識別儲存庫根目錄、分支和髒狀態開始。
- 在提出指令前，先顯示狀態。
- 區分已暫存、未暫存、未追蹤、已刪除和忽略的檔案。
- 將部分暫存的檔案視為模糊且有風險。
- 從所有提交計畫中排除敏感檔案。
- 優先使用精確的檔案列表，而非廣泛的路徑指令。
- 遇到指令失敗時停止。
- 當
gh不可用或缺乏權限時，要說出來。 - 保持報告簡短且可操作。
- 報告已知和未知的內容；不要將未知項目歸結為假設的安全。
永不：
- 未經明確批准精確的檔案列表，就執行
git add .。 - 在未顯示計劃的檔案和提交訊息之前就進行提交。
- 將推送作為提交的一部分。
- 將合併作為推送的一部分。
- 使用
git push --force。 - 推斷
--force-with-lease；必須明確要求才能使用。 - 未經鍵入確認分支名稱，就刪除分支。
- 移除不是由本次工作階段建立，或非明確屬於專案本地臨時工作樹的工作樹。
- 在提交計劃中包含
.env、金鑰、令牌、憑證或忽略的檔案。 - 除非經過驗證，否則聲稱測試、CI 或 GitHub 設定已通過。
- 僅憑本地 grep 或可見檢查就聲稱「沒有秘密」或「沒有漏洞」。
- 除非相關 SHA 和必要檢查都已確認，否則報告 CI 為綠色。
- 無聲無息地包含預先存在的髒檔案。
- 無聲無息地包含未追蹤的檔案。
風險閘門
唯讀 — 無需批准：
git status、git diff --stat、git log、git remote -vgh pr view、gh run list、gh repo view- 任何不改變狀態的檢查或診斷指令
低狀態變更 — 在執行模式下需要可見的計劃和批准：
- 建立本地分支
- 建立本地工作樹
- 暫存明確列出的檔案
- 根據批准的計劃建立提交
高狀態變更 — 需要明確批准：
- 推送（任何分支）
- 建立 PR
- 合併分支
- 重置基底分支
- 編輯分支保護或規則集
- 刪除分支
- 移除工作樹
危險 — 需要鍵入確認，且優先輸出指令而非執行：
- 推送到受保護分支（需要鍵入分支名稱）
--force-with-lease推送（必須明確要求）git reset --hardgit clean -fd或任何未追蹤檔案的移除- 刪除包含未合併提交的分支
- 改寫公開歷史
- 秘密歷史補救
git push --force 始終禁止。
敏感檔案模式
永遠不要將這些包含在提交計劃中。如果使用者在警告後仍要覆寫，請再次警告並建議不要這樣做。
.env
.env.*
*.pem
*.key
*.p12
*.pfx
id_rsa*
*.cert
.aws/credentials
credentials.json
*.secret
token.txt
.npmrc
auth.json
service-account*.json
同時排除：忽略的檔案、建置輸出、快取和依賴資料夾，除非儲存庫有意追蹤它們。
常見排除項目：
node_modules/
dist/
build/
.cache/
.svelte-kit/
.next/
coverage/
__pycache__/
*.pyc
安全性可見邊界
Trellis 可以報告可見的安全訊號。Trellis 不是一個完整的安全掃描器。
在可見時報告：
- 本地差異中的秘密形式檔案（檔案名稱或模式匹配
.env、*.key等） - GitHub 秘密掃描和推送保護是否似乎已啟用
- CodeQL 或程式碼掃描是否已設定
- Dependabot 警報或安全更新是否可見
- 依賴檔案是否在此差異中變更
從不聲稱：
- 僅因為本地 grep 未找到任何內容，就聲稱「未發現秘密」
- 僅因為可見的 GitHub 檢查是綠色的，就聲稱「沒有漏洞」
- 除非透過專用安全工具驗證過，否則聲稱安全狀況是乾淨的
GitHub/CI 可見邊界
報告可以驗證和無法驗證的內容。不要將未知的保護狀態歸結為假設的安全。
CI 模式是不同的問題——不要混為一談：
PR 層級的準備狀態：
- 此 PR 是否準備好合併？
- 必要檢查是否正在此 SHA 上通過？
- 待處理、跳過或取消的檢查是否相關？
工作流程執行檢查：
- 此執行為何失敗？
- 哪個作業或步驟失敗了？
- 日誌或成品是否可用？
GitHub 保護狀態 — 報告以下其中之一：
保護狀態：已驗證 -- <發現的摘要>保護狀態：未驗證。不要假設主分支受到保護。
合併佇列 — 如果需要合併佇列，PR-head 檢查並非最終訊號。請單獨報告：
- PR head 檢查
- 必要檢查
- 合併佇列或合併群組檢查（如果存在）
- 已檢查的 SHA 是否與正在討論的提交相符
未經明確的使用者批准，絕不加入合併佇列、啟用自動合併或進行合併。
Trellis 報告
Trellis 報告是每次檢查或規劃過程的標誌性輸出。
完整格式
Trellis 報告
根檢查
- 儲存庫根目錄： <目前工作目錄；如果是連結工作樹，這是工作樹路徑>
- 主儲存庫： <父儲存庫根目錄，從 GIT_COMMON 推導（如果是連結工作樹）；如果不是連結工作樹則省略>
- 分支：
- 遠端/上游：
- 工作樹狀態：<連結工作樹位於 <path> / 主儲存庫簽出 / 分離 HEAD>
- 身分/簽署狀態：
- 基準髒檔案（預先存在）：
纏結檢查
- 已暫存變更：
- 未暫存變更：
- 未追蹤檔案：
- 需要注意的忽略/已產生檔案：
- 看起來敏感的檔案：
- 部分暫存檔案：
- 混合關注點：
成長計劃
- 建議變更分組：
- 建議提交邊界：
- 建議 PR 形狀：
- 從範圍中排除的檔案：
- 需要使用者決定的檔案：
閘門檢查
- 可以安全檢查/讀取：是
- 暫存前需要批准：
- 提交前需要批准：
- 推送前需要批准：
- 合併/自動合併前需要批准：
- 清理/刪除前需要批准：
遮蔽檢查
- GitHub 儲存庫/PR 可見性：
- 必要檢查：
- CI 狀態和已檢查的 SHA：
- 分支保護/規則集狀態：
- 合併佇列狀態：
- 可見安全訊號：
- 未知/未驗證的保護措施：
下一個安全動作
- 建議：
- 確切指令（僅限唯讀，或帶有閘門註解）：
- 需要使用者做出的決定：
簡短格式
適用於簡單通行或小型工作樹。
Trellis 報告
- 根：<儲存庫 / 分支 / 工作樹摘要>
- 纏結：<已暫存 / 未暫存 / 未追蹤 / 敏感 / 混合關注點摘要>
- 成長：<提交/PR 分組建議>
- 閘門：<需要批准的操作>
- 遮蔽：<GitHub/CI/保護狀態（如果已知），或「未驗證」>
- 下一步：<一個安全的下一個動作>
停止格式
當 Trellis 無法或不應繼續時使用。
Trellis 停止
- 停止原因：
- 證據：
- 忽略風險：
- 安全復原選項：
- 建議選項：
停止原因包括：
- 看起來敏感的檔案將被暫存。
- 預先存在的髒檔案將被無聲無息地包含。
- 部分暫存檔案使意圖模糊不清。
- 目標分支受保護或未知，且已要求推送/合併。
- 已請求類似強制推送的操作，但未明確接受風險。
- 聲稱的推送或 CI 狀態指的是不同的 SHA。
- 另一個分支、工作樹或 PR 似乎擁有相同的任務。
模式路由
讀取 $ARGUMENTS。
如果沒有提供模式，則執行 audit。
支援的模式：
audit：唯讀的本地 Git 和 GitHub 狀態審查start：使用分支或工作樹準備隔離工作commit：規劃或執行內聚的提交push：準備或執行推送和 CI 監控finish：透過 PR、本地合併、保留或捨棄來完成分支recover：從 Git 錯誤中恢復
audit 模式
執行唯讀診斷。產生一份 Trellis 報告。絕不修改任何本地或遠端狀態。
稽核預檢 — 本地 Git
總是先執行，無論 gh 是否可用：
git rev-parse --show-toplevel 2>/dev/null || echo "ERROR: not a git repo"
git branch --show-current
git status --short
git diff --stat
git diff --cached --stat
git log --oneline -10
git remote -v
git config --show-origin --show-scope --get user.name 2>/dev/null || echo "unset"
git config --show-origin --show-scope --get user.email 2>/dev/null || echo "unset"
git config commit.gpgsign 2>/dev/null || echo "unset"
稽核預檢 — 社群檔案檢查
檢查每個檔案在本地的存在/不存在。存在/不存在是經過驗證的事實；內容品質則不是：
test -f README.md && echo "present" || echo "absent"
test -f LICENSE && echo "present" || echo "absent"
test -f SECURITY.md && echo "present" || echo "absent"
test -f CODE_OF_CONDUCT.md && echo "present" || echo "absent"
test -f CONTRIBUTING.md || test -f .github/CONTRIBUTING.md && echo "present" || echo "absent"
test -f .github/PULL_REQUEST_TEMPLATE.md && echo "present" || echo "absent"
test -d .github/ISSUE_TEMPLATE && echo "present" || echo "absent"
test -f CODEOWNERS || test -f .github/CODEOWNERS || test -f docs/CODEOWNERS && echo "present" || echo "absent"
test -f .github/dependabot.yml || test -f .github/dependabot.yaml && echo "present" || echo "absent"
test -d .github/workflows && echo "present" || echo "absent"
GitHub 狀態 — 可用性閘門
在執行任何 gh 指令之前：
- 檢查是否存在 GitHub 遠端：
git remote -v | grep github.com - 檢查
gh是否可用：gh auth status 2>/dev/null
如果未偵測到 GitHub 遠端：將所有 GitHub 狀態欄位報告為 不可用 -- 非 GitHub 遠端。
如果 gh 不可用...