documentation

ドキュメントとナレッジ管理の原則

• 同期更新: コードや設定に変更を加える際は、ドキュメントを同時に更新する。README、API 仕様、.env.exampleなどを最新状態に保ち、コードとの乖離を防ぐ。
• コードコメント: コメントには「なぜそうしたか」を英語で記述し、「何をしているか」はコードが説明できる状態を維持する。

ドキュメント更新チェックリスト

• README.md: 新機能や仕様変更が反映されているか
• API 仕様書: エンドポイント、リクエスト/レスポンス形式、エラーコードが最新か
• 環境変数: .env.example に新しい環境変数が追加されているか
• アーキテクチャ図: システム構成に変更があった場合、図も更新されているか
• トラブルシューティング: 新しいエラーや対処法があれば追記されているか

---

SKILL.md 記載ルール

各スキルファイル（.github/skills/*/SKILL.md）は、以下のガイドラインに従って作成・更新します。

記載内容の原則

• 汎用的な技術知識・ベストプラクティスのみ記載

  • 他のプロジェクトでも役立つ普遍的な知見
  • 言語やフレームワークの一般的なパターン
  • 業界標準のアプローチ

• 本システム固有の要素は記載しない

  • ファイル名や関数名など具体的なコード実装
  • このプロジェクト特有のディレクトリ構成
  • 業務ルールや組織的な制約

• 具体的なコード例は必要に応じて

  • 間違いやすい内容の場合のみ具体例を示す
  • 汎用的でクリアなコード例に限定
  • 複雑すぎる実装例は避ける

スキルの粒度

• 3-5ページ程度（セクション数: 5-10）を目安
• 1つのスキルは1つの責務に特化
• 複デューシャドムの場合は別スキルに分割