Imported from baserproject/basercms (AGENTS.md). Install upstream with npx skills add baserproject/basercms. Copyright stays with the author.

開発指示書（AGENTS.md）

このリポジトリの AI エージェント向け開発指示書です。プロジェクトの開発において、これらのガイドラインに従って作業を進めてください。

このファイルは複数の AI ツール共通の指示書（AGENTS.md 規約）です。詳細な各指示書は .github/instructions/ 配下にまとめています。

指示書一覧

basic.instructions.md

基本的な開発ガイドライン

AI エージェントが開発を行う際の基本的なルールとベストプラクティスを定義しています。

• 基本ルール: 要件に従った作業進行、自律的な問題解決、既存コードの尊重
• 技術スタック: プロジェクト定義に従った技術選定
• セキュリティ: 機密情報の適切な取り扱い、ユーザー入力検証
• コーディング: シンプルで読みやすいコード、適切な命名、エラーハンドリング
• ベストプラクティス: 再利用可能なコンポーネント作成、パフォーマンス・アクセシビリティ対応

basercms.instructions.md

baserCMS 開発全般のガイドライン

baserCMS（PHP8 + CakePHP5 ベース）の開発についての包括的な指示書です。

• アーキテクチャ: プラグインベースの構成、Contents/CustomContent サービス分離
• 開発・テスト: Docker コンテナでのユニットテスト実行、API テストのトークン認証
• コーディング規約: クラスメソッド追加時の配置ルール、テスト構成
• ディレクトリ構成: プラグイン/テーマの配置、設定ファイルの場所
• API 連携: REST API の認証方式、エンドポイント構成

basercms-custom-content.instructions.md

baserCMS カスタムコンテンツ開発ガイド

baserCMS のカスタムコンテンツ機能に特化した開発指示書です。

• テンプレート配置: テンプレートの配下場所
• データ表示: カスタムエントリーの値表示方法
• アーカイブページ: 選択リストフィールドによる自動URL生成、でのタイトル参照方法など
• ナビゲーション: 前後エントリーリンクの実装パターン
• 特殊表示: 画像表示、テキストエリアの改行処理
• CSS 作成: 既存テーマへの追加時の注意点

local.instructions.md

ローカル開発環境の設定

ローカル環境での特有のユニットテスト実行の方法などを記載しています。 基本的に .gitignore にて、コミット対象外になっており、存在しない場合があります。

cloud.instructions.md

クラウド実行環境（Claude Code on the web）の設定

クラウドセッション上で開発する際の特記事項を記載しています。セットアップ手順の全体像は docs/cloud/README.md を参照してください。

• 実行環境の判定: 環境変数 CLAUDE_CODE_REMOTE_SESSION_ID の有無
• 作業開始前の確認: docker/bin/cloud-status.sh で起動完了を待つ
• コンテナ名: 実行環境によって PHP コンテナ名が異なる場合がある（クラウドは bc-php、ローカルは local.instructions.md の記載に従う）。いずれの場合も実行前に docker ps で実際に確認すること

クラウドセッションでは、セッション開始時とアイドル再開後の両方で docker/bin/cloud-status.sh を実行し、READY を待ってから作業を始めること。 docker ps の結果だけで起動を判断しないこと（docker compose up の途中だと 一部のコンテナしか出ず、未起動と誤読する）。アイドル再開では SessionStart フックが 発火しないことがあり、そのときは cloud-status.sh だけが復旧の入口になる。

使用方法

1. プロジェクトの種類に応じて、該当する指示書を参照してください
2. 基本的な開発ルールは basic.instructions.md を基準とします
3. baserCMS 開発では basercms.instructions.md を主要ガイドラインとして使用
4. カスタムコンテンツ開発時は basercms-custom-content.instructions.md を追加参照
5. ローカル環境でのテスト実行時などは local.instructions.md の設定を確認
6. クラウドセッション（Claude Code on the web）での作業時は cloud.instructions.md を確認

シェルコマンド実行時の注意

• パイプ（|）や複合コマンドを避ける。コマンドA | コマンドB のように繋ぐと権限の自動承認が効かず確認プロンプトが発生するため、原則として単一コマンドで実行する。
• フィルタや整形が必要な場合は、パイプで繋がずスクリプト側で必要な出力を完結させる、または段階的に複数回に分けて実行する。
• 安全な読み取り専用コマンド（grep / find / ls / cat / sed -n / head / tail 等）は許可リスト（.claude/settings.local.json）で自動承認済み。これらも単体で使う。

ブランチ運用時の注意

• main ブランチや開発ブランチ（5.3.x / 5.4.x など）へ直接プッシュしない。 作業は必ずトピックブランチで行い、プルリクエスト経由で取り込むこと。

• やむを得ず直接プッシュが必要な場合は、実行前に必ずユーザーへ確認を取る。 AI エージェントの判断だけで直接プッシュしてはならない。

• 指示されたブランチ以外へプッシュする場合も、同様に事前確認を必須とする。

• プルリクエストがマージ済みかどうかを、プッシュ前に必ず確認する。 マージ済みのプルリクエストは新しいコミットを追跡できないため、追加の変更は 新しいトピックブランチを切って別のプルリクエストとして起票すること。

• トピックブランチ名には、内容に応じた種別 prefix を付ける。

  • fix/ … バグ修正
  • feature/ … 機能追加・改善
  • security/ … セキュリティ対応
  • docs/ … ドキュメントのみの変更

  prefix に続けて、内容が分かる名前を英小文字ハイフン区切りで付ける。 例: fix/setup-script-wait-hang

• AI ツールが自動生成した作業ブランチ名（claude/... など）をそのまま使うのは、 そのセッションでブランチを指定された場合のみとする。エージェントが新規に ブランチを切る場合は、上記の種別 prefix を使うこと。

コミット・プルリクエスト作成時の注意

本リポジトリはパブリックリポジトリであり、コミットメッセージやプルリクエストの 本文は誰でも閲覧できる恒久的な記録として残る。以下を守ること。

タイトル

• タイトルは日本語で作成する。コミットメッセージの1行目、プルリクエストの タイトルのいずれも日本語とする。
• 解消対象の Issue がある場合は、タイトルに fix #{Issue番号} を含める。 例: fix #4499 TRUST_PROXY=true 環境で判定が誤る問題を修正

本文

• AI ツールのセッション URL を含めない。https://claude.ai/code/session_... の ような作業セッションへのリンクは、作成者本人しか開けず、レビュアーにとっては 意味を持たない内部リンクとなるため、コミットメッセージ・プルリクエスト本文・ コードコメントのいずれにも記載しない。
• 同様に、ローカル環境の絶対パス・内部ホスト名・環境変数の値・認証情報など、 リポジトリ外の情報を持ち込まない。
• AI が関与したことの明示は残す（むしろ推奨）。コミットの Co-Authored-By:、 プルリクエスト本文やコメント末尾の生成ツール表記がこれにあたる。 エージェントは GitHub へ操作者本人のアカウントで書き込むため、これらの表記が AI による記述であることを読み手が判別する手がかりとなる。 AI 関与の表明と、内部リンクの混入は別の問題として扱う。
• ツール側が自動でセッション URL を付与した場合（プルリクエスト作成 UI など）は、 作成後に本文から当該行を削除すること。

使用言語

コードレビューのコメントや説明はすべて日本語で行ってください。

これらのガイドラインに従って、一貫性のある高品質なコードの開発を行ってください。