command-execution

コマンド実行ガイドライン

これは厳格なガイドラインです。 以下のルールを正確に守ってください。

コマンドの実行やスクリプトの実行に関する AI エージェント向けガイドラインです。

---

基本ルール

1. ホストマシンでプロジェクトのツールを実行しない

ホストマシンは常にクリーンな状態に保ちます。 すべてのプロジェクトツール（pnpm、npm、python、pip、pytest、cargo など）は devcontainer 内にあります。パッケージのインストール、ビルドの実行、プロジェクトコマンドの実行をホスト上で直接行わないでください。

プロジェクトで何かを実行する必要がある場合は、devcontainer を使用してください。

# ✅ Correct: execute inside the container
docker exec -it <container_name> pnpm install
docker exec -it <container_name> pnpm build
docker exec -it <container_name> pytest

# ❌ NEVER: run project tools on the host
pnpm install          # installs to host, pollutes system
pip install requests  # modifies host Python
npm run build         # uses host Node version, may differ from container

例外（ホスト上で使用してよいツール）：

• git — バージョン管理はホスト側で行います
• docker / docker compose — コンテナを管理します
• gh — リポジトリ操作用の GitHub CLI
• npx skills — スキルのインストール（プロジェクトの依存関係は変更しません）
• ファイル操作（cat、ls、grep、find など）

コンテナの外から複数のプロジェクトを横断して作業する場合は、ファイルの読み取り、git 操作、docker コマンドに限定してください。ビルド、テスト、インストールが必要な場合は、コンテナ内で exec を実行してください。

2. プロジェクトの開発者向け API を使用する

必ずルートの package.json スクリプトを使用してください。

# ✅ Correct
pnpm lint
pnpm provision:dev
pnpm build:frontend

# ❌ Wrong
cd infrastructure && npx cdk deploy
cd frontend && npm run build

理由：ルートスクリプトは開発者向け API です。これを迂回すると、誰にも気づかれないまま API が壊れる可能性があります。

2. cd を使用しない

# ❌ Wrong
cd infrastructure && pnpm synth

# ✅ Correct
pnpm synth:dev

# ✅ Or use working_dir parameter
execute_bash(command="pnpm synth", working_dir="infrastructure")

理由：cd での移動は持続しません。ルートスクリプトまたは working_dir パラメーターを使用してください。

3. 先にスクリプトを確認する

# Check available scripts
cat package.json | grep -A 50 '"scripts"'

次を確認してください：lint、test、build、provision:*、deploy:*

---

インストール

# ✅ Workspace root (shared)
pnpm add -D -w eslint

# ✅ Specific workspace
pnpm add -D eslint --filter frontend

# ❌ Wrong
cd frontend && pnpm add eslint

---

直接実行が必要な場合

1. まずルートスクリプトが存在するか確認します
2. 使用できる場合は working_dir パラメーターを使用します
3. ルートスクリプトを使用しない理由を記録します

---

まとめ

基本ルール：

1. ✅ ルートの package.json スクリプトを使用する（開発者向け API）
2. ✅ コマンドで cd を使用しない
3. ✅ 利用可能なスクリプトを先に確認する
4. ✅ 直接実行する場合は working_dir パラメーターを使用する

覚えておいてください：ルートスクリプトはプロジェクトの公開 API です。これを迂回すると、契約が破られます。

---

継続的な改善

このスキルで防げるはずの動作について開発者から修正を受けた場合は、今後同じ修正が必要にならないよう、このスキルに加える具体的な変更を提案してください。