ベストプラクティス参照

公式・コミュニティの一次情報。

ベストプラクティス参照（公式・コミュニティ）

区分	タイトル	要点
Cursor 公式	エージェント BP（2026-02）	Plan first · コンテキスト節約 · Rules/Skills/Commands · Hooks · 検証可能なゴール
Cursor 公式	Agent Skills	ディレクトリ · `paths` · `/migrate-to-skills` · 入れ子
Cursor 公式	Rules	`.mdc` · `AGENTS.md` · Remote Rules（GitHub）
Anthropic 公式	Claude Code BP	コンテキスト管理 · 検証ループ · Explore→Plan→Implement · 具体プロンプト
標準	Agent Skills 仕様	クロスツール互換 · Progressive Disclosure
Zenn	Skills 作成 Tips	`SKILL.md` は薄く · 詳細は scripts/references
Zenn	Skills ハンズオン	description 設計 · 粒度 · セキュリティ
Zenn	AGENTS.md と Rules	`AGENTS.md` + `globs` · Skills は別レイヤ
Qiita	5ツール Skills 比較	`.agents/skills/` 共有 · Remote import
Qiita	Skills パラダイム解説	オープン標準化 · `/migrate-to-skills` の位置づけ
X	@leerob — エージェント実践（2025-06）	検証ループ（高速テスト・型・lint）· Cursor＝IDE/ diff · Claude Code＝ループ · Codex＝背景レビュー
X	@bcherny — 本人のセットアップ（2026-01）	並列 worktree · Plan→Build · CLAUDE.md 共有 · Hooks · 検証で品質 2–3x
X	@bcherny — チーム Tips（2026-01）	worktree 並列 · Plan に注力 · Skills 化 · サブエージェント · 音声入力
X	@bcherny — 隠れ機能（2026-03）	`/loop` · teleport · Chrome 拡張検証 · `/batch` · `--add-dir`
X	@commte — 大規模 CB 要約	薄いルート CLAUDE.md · サブディレクトリから開始 · Stop hook
X	@NainsiDwiv50980 — セットアップ 12 項	環境整備 · MCP · worktree · CI 連携（4章）

X（公開スレッド）ベストプラクティス要約

Loop engineering（横断 · 2026-06）

出典	推奨	置き場
@steipete	プロンプトではなくループ設計。エージェントに都度指示しない	Loop 早見
Addy Osmani	5+1 部品 · `/goal` · maker–verifier · トークンコストに注意	同上 · agent-skills
@reach_vb	Automations · Worktrees · Skills · Connectors · Sub-agents + 状態ファイル	Skills · worktree
@samueljmcd	検証ゲート（verifier）が本体。テスト通過≠本番	18章検証
@weswinder	トークン上限下では人間の確認が要る — 無限自律は現実的でない	方針

Cursor

出典（X）	推奨	本サイトでの置き場
@leerob（Cursor VP DX）	エージェントに自己検証ループを渡す — 高速テスト・型付き言語・lint。エージェントはコンパイル/テスト失敗を読んで自己修正する	Cursor 公式 BP · 18章検証
同上	Cursor は IDE として diff レビュー・インライン編集に強い。1 ツール万能ではなく用途分担（Plan は Cursor、長いループは Claude Code 等）	2章 Cursor · 横断表
公式 BP（X 以外の正本）	Plan Mode（`Shift`+`Tab`）→ 計画承認 → Build。ズレたら follow-up ではなく計画を直して再実行	Plan Mode 公式 · @Past Chats

Claude Code

出典（X）	推奨	本サイトでの置き場
@bcherny セットアップ	ターミナル 5 + Web 5–10 セッション並列 · Opus + thinking · 共有 `CLAUDE.md` を git 管理 · PR で `@.claude` 学習	Claude 公式 BP · 18章並列
同上	複雑タスクは Plan mode（`Shift`+`Tab`×2）→ 計画 OK なら auto-accept で 1-shot · PostToolUse で format · 検証手段が最重要（品質 2–3x）	Phase1 CLAUDE
@bcherny チーム Tips	git worktree で 3–5 並列が最大の生産性 · 計画に時間を使い実装は 1-shot · 修正のたび「CLAUDE.md を更新せよ」· 1 日 2 回以上の作業は Skill 化	セットアップ 12 項 · Skills 配置
@bcherny 隠れ機能	`/loop` で PR 監視・rebase 自動化 · `/teleport` で Web↔CLI · Chrome 拡張で UI 検証 · `/batch` で大規模 migration · `claude -w` worktree	サブエージェント
@0xchromium workflows	チャット≠ワークフロー。ROLE · TOOLS · TRIGGER · OUTPUT。最初は1本（朝ブリーフィング / CI digest）	一般4要素 · 開発WF
addyosmani/agent-skills	Addy Osmani の 24 Skills + 7 コマンド（Define→Ship）。検証ゲート・anti-rationalization 付き。`/build auto` は計画1回承認後にタスク自律実行	早見 · Phase · Skills
@samueljmcd loop	ループ設計より検証ゲート（verifier）が本体。Closed loop · inner/outer · maker–verifier。Bun port 事例はテスト通過≠本番	Loop 早見 · 18章検証
@commte 要約	ルート CLAUDE.md は薄く · 作業はサブディレクトリから · Hooks→Skills→Plugins→MCP · Stop hook で学びを CLAUDE.md へ	大規模 CB
@obsidianstudio9 claude-obsidian	`/wiki` · ingest · `index.md`/`hot.md` でセッション跨ぎ。本番 Vault ではなくサンドボックス推奨	claude-obsidian · Obsidian MCP
@noisyb0y1 gstack	Garry Tan の Phase 型 Skills（`/office-hours` · `/plan-eng-review` · `/qa` · `/ship`）。公式 gstack を正とする	gstack 早見 · Phase 地図

Codex

出典	推奨	本サイトでの置き場
@leerob（Codex 言及）	サイドプロジェクトで背景エージェントとして利用 — アーキテクチャ批判的レビュー・「コードの理解」を説明させ比較・明らかなバグ/ red flags 探索	2章 Codex
OpenAI 公式 BP（X より正本）	`AGENTS.md` に実行可能コマンド・禁止事項 · `/init` で下書き→人手で削る · 32 KiB 上限 · 同じミス 2 回で AGENTS.md 更新	Codex 公式 BP · Phase1 テンプレ
同上	検証: `codex --ask-for-approval never "Summarize the current instructions."` で読み込み確認 · モノレポはネスト `AGENTS.md` / `AGENTS.override.md`	AGENTS.md サンプル

本サイトにまだ無い / 別章の新しめ手法（Skills ページ外だが公式・開発者が推すもの）:

Cursor: Background / Cloud Agent（2章）、Automations、Settings から GitHub Remote Rules
Claude Code: /goal による完了条件、Stop hook の検証ゲート、claude -p 非対話、Subagents（18章）
横断: チームで .agents/skills/ を正本にし、Cursor Rules は短い alwaysApply のみ（Qiita Rules 入門は Rule Type の説明として参照可）

以下のサンプル・Commands は Cursor 専用（Claude は /スキル名、Codex は Skills のみ）。

Commands と Plan のサンプル

#	コマンド	いつ使う	主な参照
1	`/plan`	3 ステップ以上・設計判断あり。着手前に Done when を固定	Phase 2 Plan・`tasks/todo.md`
2	`/review`	PR 提出前のセルフレビュー	PR前チェック
3	`/pr-check`	9 カテゴリの提出前チェックを漏れなく	チェック詳細
4	`/requirements`	PRD Must を要件 doc にトレース	Phase 3
5	`/design`	要件から設計 doc（API・境界・エラー）	設計 doc 生成
6	`/tdd-cycle`	RED → GREEN → REFACTOR を 1 サイクルだけ	TDD テンプレ
7	`/verify`	完了報告前。テスト・ログ・再現手順のいずれかを示す	完了前の検証
8	`/debug`	再現はできるが原因不明。仮説→計測→局所修正	Cursor Debug モード
9	`/investigate`	「どこにある？」系。スコープ限定の調査だけ	調査の任せ方
10	`/lessons`	指摘・修正後にパターンを蓄積	`tasks/lessons.md`・lessons
11	`/adr`	技術選定・トレードオフを ADR に残す	ADR
12	`/handoff`	新規チャットへ。Past Chats + todo の引き継ぎ	@Past Chats
13	`/explain`	変更報告。触ったパスのディレクトリツリー必須	`agent-workflow-orchestration.mdc`
14	`/security`	認可・入力検証・秘密情報のレビュー	セキュリティ
15	`/fix-ci`	CI 失敗ログから再現→修正→ green 確認	自律的バグ修正
16	`/ask-spec`	コードを変えず仕様・ADR の壁打ち（Ask 推奨）	要件すり合わせ

各コマンドの使い方・例（16件）

Composer にそのまま貼れる一行と、似たコマンドとの違い。スラッシュのあとに続けた文字が $ARGUMENTS になる。

コマンド	コピペ用（一行）	混同しやすい相手
`/plan`	`/plan 請求PDFエクスポート Phase3。PRD: docs/prd/invoice-export.md。Done when: rspec green + staging 手動確認`	`/ask-spec`（まだ決めない）・`/design`（設計 doc 執筆）
`/review`	`/review 現在ブランチの差分をセルフレビュー。ブロッカーがあれば push 提案しない`	`/pr-check`（9 カテゴリ網羅）・`/security`（セキュリティ特化）
`/pr-check`	`/pr-check feature/invoice-export → main。flow-14 の 9 カテゴリを [ ]/[x] で`	`/review`（ざっくりレビュー）・`/verify`（テスト実行）
`/requirements`	`/requirements docs/prd/invoice-export.md → docs/invoice-export/01_requirements.md。Must を REQ-001 形式でトレース`	`/design`（API 詳細）・`/ask-spec`（未確定の壁打ち）
`/design`	`/design docs/invoice-export/。01_requirements.md を読み 02_design.md に API・ジョブ・エラー型`	`/requirements`（要件のみ）・`/plan`（タスク分解）
`/tdd-cycle`	`/tdd-cycle spec/services/invoice_export_spec.rb の「在庫不足で ErrInsufficientStock」1 サイクルだけ`	`/verify`（全体テスト）・Agent に「全部実装して」（サイクル無視）
`/verify`	`/verify docker compose exec app bundle exec rspec spec/services/invoice_export_spec.rb`	`/review`（コード読み）・完了報告だけ口頭（証拠なし）
`/debug`	`/debug POST /api/invoices/export が 500。staging で再現可。ログは CloudWatch の該当 request_id`	`/fix-ci`（CI ログ起点）・`/investigate`（変更しない調査）
`/investigate`	`/investigate <Service> の呼び出し元だけ。src/domain/ と src/app/。JSON {paths, summary} のみ`	メインに「全部 grep して」（ログ肥大）・`/debug`（修正まで）
`/lessons`	`/lessons レビュー指摘: push 許可なしで commit 提案された。再発防止を lessons に追記`	`/plan`（今回のタスク）・Rules へいきなり長文追加
`/adr`	`/adr PDF 生成を同期 vs ジョブキュー。docs/adr/016-*.md ドラフト。未決は todo リスクへ`	`/design`（機能設計 doc）・`/ask-spec`（決定前の相談）
`/handoff`	`/handoff Phase4 PDF ロジック続き。PR #482。次チャットで @Past Chats 1 件 + @tasks/todo.md`	会話全文コピペ・`/plan`（新規 Plan 作成）
`/explain`	`/explain 直前のコミット分。ディレクトリツリー必須。検証コマンドも添える`	「変更した」（ツリーなし）・`/review`（品質評価）
`/security`	`/security src/api/middleware/auth.ts と export エンドポイント。認可漏れ・IDOR・秘密情報`	`/review`（一般品質）・`/pr-check`（全カテゴリ）
`/fix-ci`	`/fix-ci spec/services/invoice_export_spec.rb:42 expected 200 got 500。ログ要点を再現して修正`	`/debug`（手元再現）・`/tdd-cycle`（1 サイクルだけ）
`/ask-spec`	`/ask-spec 請求PDFを同期生成 vs 非同期ジョブのトレードオフ。コード変更なし。ADR 案だけ`	`/plan`（実装着手）・`/design`（doc 確定執筆）

場面別の詳細（モード・添付・期待する返答）。

/plan — 着手前にスコープと Done when を固定

使う: 3 ステップ以上、設計判断、影響範囲が広い。使わない: 1 ファイルの typo 修正、仕様がまだ曖昧（先に /ask-spec）。

例:

/plan ユーザー招待メール再送。tasks/todo.md を更新。
Done when: 結合テスト green、staging で 1 件再送確認、docs/invite/01_requirements.md 更新

モード: Plan 推奨（Shift+Tab）→ 承認 → Build。添付: @tasks/todo.md、@docs/prd/...

返ってほしいもの: チェックリスト付き tasks/todo.md 案、リスク列挙。

/review — PR 前のざっくりセルフレビュー

使う: コミット済み・PR 直前。使わない: 公式チェックリストの網羅（/pr-check）、セキュリティ特化（/security）。

/review @Branch の差分。alwaysApply ルール違反がないか。重大度つきで

添付: @Branch または @git（環境による）。返答: ブロッカー / 警告 / OK の箇条書き。

/pr-check — 提出前 9 カテゴリの漏れチェック

使う: マージ直前の最終確認。使わない: 実装中の途中確認（重い）。

/pr-check PR #512。docs/invoice-export/ 01〜07、ADR、glossary、CI、セキュリティまで [x]/[ ]

返答: カテゴリごとの [ ] / [x]。未確認は「未確認」と明記。

/requirements — PRD → 要件 doc

使う: Phase 3 の最初。使わない: API パスや DB カラムの確定（/design）。

/requirements docs/prd/billing-v2.md の Must だけ。
出力: docs/billing-v2/01_requirements.md（REQ-xxx で PRD Must にトレース）

禁止の確認: エージェントが API を断定していないこと。

/design — 要件 → 設計 doc

使う: 01_requirements.md が揃ったあと。使わない: PRD から要件を起こす段階（/requirements）。

/design docs/invoice-export/。
@docs/invoice-export/01_requirements.md を読み 02_design.md に REST・ジョブ・エラー型

返答: 02_design.md の diff または章立て案。未決は todo リスクへ。

/tdd-cycle — TDD 1 サイクルだけ

使う: 振る舞いを 1 つ追加するとき。使わない: 機能まるごと実装依頼。

/tdd-cycle 「二重送信で 409」を spec/requests/invoices_export_spec.rb で RED→GREEN→REFACTOR 1 回

返答: どのフェーズか、変更ファイル、テスト結果 1 行。

/verify — 完了報告前の証拠

使う: 「終わった」と言う直前。使わない: コードレビューだけで完了扱い。

/verify make test と flow-17 の HTML 変更なら curl 本番 HEAD

返答: 実行コマンド、終了コード、ログ要点または再現手順。

/debug — 再現できる不具合

使う: 手元または staging で再現できる 500 / 例外。使わない: CI のみで落ちる（/fix-ci）。

/debug ローカル docker compose up 後、GET /health は 200 だが POST /export が 500。
仮説→ログ確認→最小修正

モード: Debug 推奨。返答: 原因 1 行 + 修正 diff + 再現手順。

/investigate — 調査だけ（実装しない）

使う: 呼び出し元洗い出し、設定の所在確認。使わない: バグ修正まで任せたい（/debug）。

/investigate .cursor/rules/ で alwaysApply:true のファイル一覧だけ

返答: { "paths": [...], "summary": "..." } 程度。grep 全文禁止。

/lessons — 指摘の蓄積

使う: レビュー・ユーザー指摘のあと。使わない: 初回の雑談メモ。

/lessons Mermaid エッジに <br/> を入れてパース失敗。再発防止を lessons に 1 行

返答: tasks/lessons.md 追記案。繰り返しなら Rules 昇格提案 1 条。

/adr — 設計判断の記録

使う: 技術選定が分岐するとき。使わない: 仕様未確定の壁打ち（/ask-spec）。

/adr ストレージを S3 直 PUT vs 署名付き URL。docs/adr/ 次番号でドラフト

返答: ADR ドラフト（コンテキスト・決定・代替・影響）。

/handoff — チャット切替用の引き継ぎ文

使う: 会話が長い・別機能へ移る。使わない: 同じ機能のデバッグ続き（同一会話を維持）。

/handoff 次チャット用の冒頭 3 行を書いて。Past Chats は invoice PDF セッション 1 件想定

操作: 新規チャット → @Past Chats 1 件 → 生成文を貼る → @tasks/todo.md。

/explain — 変更報告（ツリー必須）

使う: 実装・ドキュメント更新の報告時。使わない: 品質評価（/review）。

/explain さっき編集した flow-17 と .cursor/commands/ だけ。ツリー + 検証コマンド

返答: 触ったパスのツリー（1 行役割）、why、検証結果。

/security — セキュリティレビュー

使う: 認証・認可・外部入力・エクスポート機能。使わない: 文言・スタイルのみの PR。

/security 新規 middleware と /api/invoices/export。IDOR と認可漏れを重点

返答: 重大度付き findings + 修正案。

/fix-ci — CI 赤の解消

使う: GitHub Actions / CI ログが手元にある。使わない: ローカルだけで再現（/debug）。

/fix-ci RSpec: spec/models/order_spec.rb:88 Failure/Error: expected true got false。再現して green まで

返答: 原因、修正、同コマンドで green の証拠。push は許可後。

/ask-spec — コードを変えない壁打ち

使う: 要件・ADR の選択肢整理。使わない: 実装・ファイル編集（Agent / Plan）。

/ask-spec マルチテナント請求の集計単位: 組織 vs ワークスペース。Pros/Cons と ADR 案のみ

モード: Ask 必須。返答: 選択肢表、推奨、未決リスト（doc 案は書いてよいが apply しない）。

サンプル: Commands（.cursor/commands/*.md）

チャットで /review のように呼ぶ定型。Skill より短い 1 ショット向け。下は /review の最小例（全 16 件はリポジトリの .cursor/commands/ を正本とする）。

# review

PR 提出前チェックを実行する。

1. `.cursor/skills/pr-review/SKILL.md` のワークフローに従う
2. 結果を箇条書きで報告。ブロッカーがあれば push を提案しない
3. 参照: flow-14-pr-check.html のチェックリスト

/investigate でスコープを渡す例。指定スコープだけを調査し、構造化結果（パスと要約、または表）のみ返す。長い grep ログは貼らず、git 操作は行わない。

コピー用全文: Command: investigate サンプル

サンプル: Plan（全ツール共通 + Cursor 下書き）

チーム共有の正本は tasks/todo.md。Cursor Plan モードは .cursor/plans/ に下書き → 確定後 todo へ写す。タスク分解・Done when（受け入れ条件 + CI green）・リスク・レビュー結果を記録する tasks/todo.md、指摘の蓄積から Rules 昇格につなげる tasks/lessons.md、スコープとタスク分解を残す .cursor/plans/<date>-feature.md の3点をセットで使う。

コピー用全文: tasks/todo.md · tasks/lessons.md · .cursor/plans/ サンプル

" aria-label="前後の章">← リポジトリセットアップ →" aria-label="前後の章">← ガイドをまとめる設定サンプル →" aria-label="前後の章">← ガイドをまとめる設定サンプル →

AI利用開発フロー