プロジェクト構造と運用ルール ​

ディレクトリ構造 ​

repository-root/
├── AGENTS.md              # エージェント共通指示（正本）
├── CLAUDE.md / GEMINI.md  # @AGENTS.md ラッパー（編集禁止）
├── doc/agent/             # 詳細ガイド
├── doc/blog/              # ブログ記事
├── doc/categories/        # カテゴリページ
├── doc/tags/              # タグ（index.md 以外は自動生成）
├── scripts/               # 検証・生成スクリプト
└── temp/                  # 一時ファイル専用

Think Harder プロセス ​

明示されていなくても「think harder」として以下を実行する。

  • 多角的検討・影響範囲の分析
  • リスク評価・最適解の探索
  • 品質担保・副作用の予測

適用場面: ファイル編集、リンク修正、記事作成、設定変更、技術判断すべて。

テンポラリファイル ​

  • すべて temp/ 内のみ — ルートや doc/ への一時ファイル作成禁止
  • 作業完了後は削除
  • temp/ がなければ作成してから使用

リンク切れ防止 ​

ファイル移動・削除時 ​

  1. Grep で参照を全検索（例: grep -r "aws-ec2-overview" doc/）
  2. 影響しやすいファイルを確認
    • doc/index.md
    • doc/categories/*.md
    • 関連記事からのリンク
  3. リンクを正しいパスに更新
  4. npm run docs:build で確認

リンク形式 ​

種別形式例
ブログ/blog/カテゴリ/ファイル名/blog/aws/compute/aws-ec2-overview
カテゴリ/categories/カテゴリ名/categories/aws-compute
相対リンク同階層ファイル間のみ—

新規記事作成時 ​

  1. 既存リンク構造を確認
  2. kebab-case で命名
  3. doc/categories/ にリンク追加
  4. 必要に応じて doc/index.md を更新

プルリクエスト ​

  • タイトル: 🤖 [Claude] 変更内容の要約
  • 本文: 修正内容（日本語）・理由・影響範囲・Closes #XXX

ビルド ​

  • 本番同等: npm run docs:build のみ
  • 詳細: リポジトリルート VALIDATION.md