IM-BASE IM-BASE

お問い合わせ

IM Base – AI.mdガイド

IMB AI.md

【公開準備中】 IM Baseは現在、一般向けの正式公開に向けて準備を進めています。テーマのダウンロードおよび提供方法については、準備が整い次第ご案内します。

このページでは、IM BaseのAI支援開発で使用するAI.mdについて、役割や運用方法を開発者向けに説明します。

概要

AI.mdは、IM BaseでAIを活用して開発する際に参照する、現在の開発ガイドです。AIツールが従うべきアーキテクチャと実装上のルールを定義するものであり、一般利用者向けのテーマ操作ガイドではありません。

AI.mdは、README.mdやdocs/配下のドキュメントを補完します。README.mdは利用者と開発者向けの概要を提供し、その他のドキュメントには開発情報や個別のルールが記録されています。

ただし、AI.mdを読めばソースコードの確認が不要になるわけではありません。変更前には、現在の実装、関連ファイル、参照関係、フック、セレクター、生成済みアセット、関連ドキュメントなどを確認する必要があります。

  • README.md:テーマの利用者と開発者向けの概要。
  • AI.md:AI支援開発におけるアーキテクチャと実装ルール。
  • docs/current-status.md:現在の実装状況、TODO、開発履歴。

AI.mdが必要な理由

IM Baseは、Web制作会社やフリーランスの開発者がさまざまなクライアント案件で再利用できるWordPressスターターテーマです。

そのため、テーマのCoreは特定の案件に依存せず、異なるWebサイトでも利用できる状態を維持する必要があります。

IM Baseは、完成済みのデザインや案件固有のコンテンツを押し付けるのではなく、Webサイト制作に必要な共通の基盤を提供します。

AI.mdは、この境界を明確にするためのものです。明示的な依頼がない限り、案件固有の要件やデザイン上の判断をテーマのCoreに追加してはいけません。

AIによるコード変更では、実際には存在しない仕様を推測で実装したり、WordPress標準機能を重複して作成したり、既存の設計とは異なる場所へ処理を移動してしまったりする可能性があります。

また、命名規則、レスポンシブのブレイクポイント、保存済みデータなど、互換性に関わる仕様が意図せず変更されることもあります。

AI.mdでは、AIアシスタントに対して、まず現在の実装を調査し、既存のアーキテクチャに従い、要求された最小限の変更を行い、無関係なファイルや作業ツリーの変更を避けるよう指示しています。

AI.mdで定義しているルール

AI.mdでは、IM Baseを軽量なWordPressスターターテーマとして定義し、Coreが複数のクライアント案件で再利用可能な状態を維持することを求めています。明示的な要件がない限り、案件固有のコンテンツやデザインを追加してはいけません。

WordPress CoreのAPIと、ネイティブなPHP、CSS、JavaScriptを優先します。また、必要以上に装飾を増やさないアクセシブルなレスポンシブデザイン、責務の明確化、保守性、後方互換性、不要な外部ライブラリの排除を重視しています。

WordPressの初期設定、機能モジュール、テンプレート、アセット、ドキュメント、設定、翻訳などは、既存のディレクトリ構成と責務を維持する必要があります。

functions.phpはモジュールの読み込みに限定し、新しいアーキテクチャ層の追加やファイルの移動には事前のレビューが必要です。

SCSSの変更はソースファイルから行い、生成済みCSSにも変更を反映します。

レイアウト関連ファイルはページや表示領域の振る舞いを担当し、Partsは単一の責務を持つ再利用可能な共通コンポーネントとして、Partsのインデックスを通じて登録します。

JavaScriptではネイティブAPIを使用し、レスポンシブの値はwindow.imbResponsiveSettingsから取得します。

CSSのブレイクポイントと一致させ、表示モードが切り替わる際には必要な状態をリセットします。アクセシビリティに関する既存の動作や、imb-で始まるセレクター、データ属性も維持する必要があります。

ナビゲーションには、WordPressに登録されたメニューとIM Base Walkerを使用します。代替メニュー、固定ページ一覧の自動生成、core/setup.phpへのナビゲーションHTMLの実装は禁止されています。

子項目を持たないメニュー項目はリンク、子項目を持つ親項目はボタンとして扱います。サブメニューの操作方法やアニメーションは、モバイルとそれ以上の画面サイズで異なります。

WordPress API、既存のimb_theme_settings構造、翻訳関数、保存済みデータの仕様を維持することも重要です。

IM Base固有の識別子は、PHPではimb_、CSSクラスとデータ属性ではimb-を使用します。テーマ名とテキストドメインはim-baseのまま維持します。

AIを使用した開発では、変更前に関連する実装、フック、セレクター、生成済みアセット、ドキュメントを確認します。

明示的な許可なく、要件や動作を推測して追加したり、WordPressの既存機能を重複実装したり、アーキテクチャ、命名、ブレイクポイント、保存データのキー、無関係なファイルを変更したりしてはいけません。

対応するSCSSを変更せずに生成済みCSSだけを編集することも禁止されています。

ドキュメントのみの変更依頼では実装を変更しません。また、検証していない機能を完成済みとして記載したり、実装済みの内容と将来のTODOを混同したりしてはいけません。

開発時には、要件と対象外の範囲を明確にし、必要最小限の変更を行います。

その後、必要に応じて構文チェック、コンパイル、ブラウザでの動作確認、アクセシビリティ、レスポンシブ表示、git diff --checkなどを検証します。

作業結果と残っているリスクを報告し、コミットは明示的に依頼された場合にのみ実行します。

  • WordPress CoreのAPIと、ネイティブなPHP、CSS、JavaScriptを優先する。
  • SCSSを先に編集し、生成済みCSSにも変更を反映する。
  • レスポンシブのブレイクポイントはハードコードせず、window.imbResponsiveSettingsから取得する。
  • WordPress標準のナビゲーションメニューとIM Base Walkerを使用し、代替メニューやcore/setup.phpへのナビゲーションHTMLの追加を行わない。
  • IM BaseのPHP識別子にはimb_、CSSクラスとデータ属性にはimb-を使用する。
  • 変更前に現在のコードを調査し、要求された最小限の変更を行い、検証する。コミットは明示的に依頼された場合のみ実行する。

AIコーディングアシスタントでAI.mdを使用する方法

Codex、Claude Code、その他のAIコーディングアシスタントを使ってIM Baseを開発する場合は、変更前にAI.mdを読むよう明示的に指示してください。

AIツールが自動的にこのファイルを読み込むとは限りません。

まず実装したい要件と、変更してはいけない範囲を伝えます。

そのうえで、対象となる実装だけでなく、関連ファイル、参照関係、フック、セレクター、生成済みアセット、ドキュメントを調査するよう依頼してください。

要件を満たす最小限の変更を求め、無関係なファイルは対象外にします。

作業後は、必要な構文チェック、コンパイル、対象機能のブラウザ確認、git diff --checkを実行します。

変更ファイル、実際の動作、検証結果、残っているリスクを自分でも確認してください。

コミットはレビュー後、明示的に必要な場合にだけ依頼します。

AIへの指示例

Before making changes, read AI.md and follow the project rules.
Investigate the current implementation first.
Do not change unrelated files.
Do not commit.
  • 実装する要件と、変更対象外の範囲を明確にする。
  • 変更前にAI.mdを読むよう指示する。
  • 関連ファイル、フック、セレクター、生成済みアセット、ドキュメントを調査する。
  • 要件を満たす最小限の変更を実装する。
  • 必要なLint、テスト、コンパイル、ブラウザ確認、git diff --checkを実行する。
  • 結果を確認してから、必要に応じてコミットを依頼する。

AI.mdとその他のドキュメントの関係

README.mdは、現在のテーマについて利用者と開発者向けの概要を提供します。

AI.mdは、プロジェクト構成、コーディング規約、開発手順など、AI支援開発におけるアーキテクチャと実装ルールを定義します。

README.mdやdocs/配下のドキュメントを補完するものであり、現在のソースコードを調査する作業の代わりにはなりません。

docs/current-status.mdには、現在の実装状況、未完了の作業、注意点、開発履歴が記録されています。

docs/prefix-naming-rule.mdのような個別のドキュメントには、識別子の接頭辞など、特定の項目に関する詳しいルールが定義されています。

ドキュメントを変更する際は、関連するMarkdownファイルとの矛盾がないか確認し、記載されているルール、実装状況、個別のガイドの整合性を維持してください。

  • README.md:現在のテーマについて、利用者と開発者向けに説明する概要。
  • AI.md:AI支援開発で必ず従うべきアーキテクチャと実装ルール。
  • docs/current-status.md:現在の実装状況、未完了の作業、注意点、開発履歴。
  • 個別ドキュメント:接頭辞の命名規則など、特定の項目に関する詳細なルール。

AI.mdを最新の状態に保つ

新しいアーキテクチャ上の決定が正式なプロジェクトルールになった場合は、AI.mdを更新してください。

例えば、ディレクトリの責務やモジュール読み込み方式、SCSSと生成済みCSS、JavaScriptとレスポンシブ動作、ナビゲーションの仕様、WordPress APIや保存済みデータ、命名規則、開発手順などに変更があった場合です。

また、AIアシスタントが同じ誤りを繰り返す場合は、既存ルールの説明が曖昧だったり、不足していたりする可能性があります。その場合は、AI.mdの記述を明確にしてください。

変更を確定する前には、現在の実装や関連ドキュメントと照合し、ソースコードと開発ルールの整合性を確認します。

検証していない動作を、確定した仕様として記録しないことも重要です。

  • 新しいアーキテクチャ上の決定が、正式なプロジェクトルールになった場合。
  • ディレクトリの責務やモジュール読み込み構造を変更した場合。
  • SCSS、生成済みCSS、JavaScript、レスポンシブ、ナビゲーションの仕様を変更した場合。
  • WordPress API、命名規則、互換性、保存データに関するルールを変更した場合。
  • AIアシスタントが同じ誤った実装上の判断を繰り返している場合。