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レイヤー）
スキルは危険な操作を検査、報告、およびゲートします。追加のフックやGitHubアクセスなしで、通常のGitリポジトリで動作します。これは行動に依存します-エージェントがスキルに従うことに依存します。
レイヤー2: ローカルGitフック
リポジトリローカルのフックは、コミットまたはプッシュ中に実行できます。Trellisはフックを推奨する場合がありますが、v1では必須またはインストールしません。フックは欠落している可能性があり、--no-verifyでバイパスされたり、クローン間で共有されなかったりする可能性があります。
レイヤー3: Claude Codeフック
ホストレベルのフックは、ツールの使用、ファイル変更、および権限に関連して動作できます。オプションの強化のみ-スタンドアロンコアには必須ではありません。インストールされていることを想定しないでください。
レイヤー4: GitHub保護
GitHub側の強制：ブランチ保護、ルールセット、必須チェック、必須レビュー、署名付きコミット、強制プッシュ制限、マージキュー、シークレットスキャン、コードスキャン、Dependabot。APIアクセスが許可されている場合は検査して報告します。保護が存在することを決して想定しないでください。
非等価ルール:
- スキル規律はフックではありません。
- ローカルフックはGitHubのブランチ保護ではありません。
- ローカルのgrepパスはシークレットスキャンではありません。
- PRヘッドチェックはマージキューチェックではありません。
- 表示される緑色のチェックは、関連する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保護状態 - 次のいずれかを報告:
保護状態: 検証済み -- <見つかったものの概要>保護状態: 未検証。mainが保護されていると想定しないでください。
マージキュー - マージキューが必要な場合、PRヘッドチェックは最終的なシグナルではありません。個別に報告:
- PRヘッドチェック
- 必須チェック
- マージキューまたはマージグループチェック（存在する場合）
- チェックされたSHAが議論されているコミットと一致するかどうか
明示的なユーザー承認なしに、マージキューに追加したり、自動マージを有効にしたり、マージしたりしないでください。
Trellis レポート
Trellis レポートは、すべての検査または計画パスの主要な出力です。
完全形式
Trellis レポート
ルートチェック
- リポジトリルート: <現在の作業ディレクトリ; リンクされたワークツリーの場合はワークツリーパス>
- メインリポジトリ: <親リポジトリルート、リンクされたワークツリーの場合はGIT_COMMONから派生; リンクされたワークツリーでない場合は省略>
- ブランチ:
- リモート/アップストリーム:
- ワークツリー状態: <リンクされたワークツリー（<パス>）/ メインリポジトリチェックアウト / 分離HEAD>
- アイデンティティ/署名状態:
- ベースラインダーティファイル（既存）:
タングルチェック
- ステージング済み変更:
- ステージング前変更:
- 追跡されていないファイル:
- 注目すべき無視/生成ファイル:
- 機密に見えるファイル:
- 部分的にステージングされたファイル:
- 混在する懸念事項:
成長計画
- 提案された変更グループ:
- 提案されたコミット境界:
- 提案されたPR形状:
- スコープから除外されたファイル:
- ユーザーの判断が必要なファイル:
ゲートチェック
- 検査/読み取りは安全: yes
- ステージング前に承認が必要:
- コミット前に承認が必要:
- プッシュ前に承認が必要:
- マージ/自動マージ前に承認が必要:
- クリーンアップ/削除前に承認が必要:
キャノピーチェック
- GitHubリポジトリ/PR可視性:
- 必須チェック:
- CI状態とチェックされたSHA:
- ブランチ保護/ルールセット状態:
- マージキュー状態:
- 可視のセキュリティシグナル:
- 未知/未検証の保護:
次の安全なアクション
- 推奨:
- 正確なコマンド（読み取り専用のみ、またはゲート注釈付き）:
- ユーザーからの判断が必要:
短い形式
シンプルパスまたは小さなワーキングツリーに使用します。
Trellis レポート
- ルート: <リポジトリ / ブランチ / ワークツリーの概要>
- タングル: <ステージング済み / ステージング前 / 追跡されていない / 機密 / 混在懸念の概要>
- 成長: <コミット/PRグルーピングの推奨>
- ゲート: <承認が必要な操作>
- キャノピー: <既知の場合はGitHub/CI/保護状態、または「未検証」>
- 次: <1つの安全な次のアクション>
停止形式
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 が利用できない場合...