md-docs

Markdown ドキュメント

実際のコードベースの状態と照合してプロジェクトのドキュメントを管理します。記述する前に構造、ファイル、パターンを分析し、確認せずに生成してはいけません。

作業ルール

• 既存のドキュメントを読み、編集する前に、その記述が実際のコードやコマンドと一致することを確認してください。
• コンテキストを要約する際は、依頼の優先順位、外部アクションの境界、証拠の基準、失敗の帰属ルールを維持してください。
• 作業の副作用として CONTRIBUTING.md や DOCS.md を作成してはいけません。各ワークフロー固有の作成制限に従ってください。
• 横断的な規約はメインのコンテキストファイルから見つけられるようにし、変わりやすい情報を重複して記載しないでください。
• 実際に行った編集と確認を報告してください。確認せずに、コードスニペットや外部識別子を検証済みだと主張してはいけません。

移植性

AGENTS.md は汎用コンテキストファイルであり、Claude Code、Codex、Kilocode で動作します。「コンテキストの初期化」または「コンテキストファイルの更新」ワークフローの場合のみ、AGENTS.md がなく CLAUDE.md が存在する場合は、事前にユーザーへ確認してください（Claude Code では AskUserQuestion を使用します。未ロードの場合は ToolSearch select:AskUserQuestion でロードしてください。Codex では request_user_input を使用します。利用できない場合は、チャットで番号付きの選択肢を提示してください）。その後、mv CLAUDE.md AGENTS.md を実行します。別のタスクの副作用として移行してはいけません。

CLAUDE.md のシンボリックリンクは任意の互換性対応であり、必須の手順ではありません。Claude Code v2.1.277 以降は、作業ディレクトリまたはその上位に CLAUDE.md、.claude/CLAUDE.md、CLAUDE.local.md のいずれも存在しない場合、AGENTS.md をネイティブに読み込みます。これら3つのいずれかが存在すると、読み込みが黙って停止するため、その旨を知らせてください。CLAUDE.md だけを読み込むハーネスやセッションには、@AGENTS.md を含む CLAUDE.md を提示してください。ln -s AGENTS.md CLAUDE.md を提示するのは、Windows を使うコントリビューターがいない場合に限ります（core.symlinks が有効でないクローンでは、1行のテキストファイルになります）。Edit/Write はシンボリックリンク経由の書き込みを拒否します。ユーザーから削除を求められない限り、既存のシンボリックリンクを維持してください。詳細と修正方法：init-agents.md、「Claude Code compatibility」セクション。

このスキルで「コンテキストファイル」とは、AGENTS.md（およびシンボリックリンクまたは @AGENTS.md のインポートとして存在する場合は CLAUDE.md）を指します。

モノレポ

複数のパッケージを含むリポジトリですか？update-*／init-* の一括処理を行う前に、monorepo.md を読んでください（探索コマンド、ファイルごとのスコープ設定、コンテキスト読み込みルール）。対象を列挙してください。一括処理によって3つを超えるファイルを作成または書き換える場合は、停止し、書き込み前に予定する対象を列挙して確認を得てください（上記「移植性」と同じ確認方法を使用します）。

引数

これらはユーザー依頼の修飾子として扱ってください。依頼にフラグまたは同等の表現が含まれている場合に適用します。すべてのワークフローで次の項目に対応します。

• --dry-run：変更を差分としてプレビューし、書き込みは行いません
• --preserve：既存の構造を維持し、不正確な箇所だけを修正します
• --minimal：概要レベルの構造のみを対象に、簡易的に確認します
• --thorough：すべてのファイルを詳細に分析します

バックアップの取り扱い

上書きする前に、排他的に作成する方法（例：mktemp FILE.backup.XXXXXX）で、隣接する一意のバックアップパスを作成してください。元ファイルのバイト列を新しいパスにコピーしてください。バックアップパスを報告してください。作成またはコピーに失敗した場合は、元ファイルを上書きする前に停止してください。既存のバックアップを置き換えたり、自動削除したりしてはいけません。

報告形式

各操作の後に、概要を表示してください。

[OK] Updated AGENTS.md
  - Fixed build command
  - Added new directory to structure

[OK] Updated README.md
  - Added installation section
  - Updated badges

[--] CONTRIBUTING.md not found (skipped)

検証

• 更新したドキュメント内のすべての事実の記述を、現在のコードベースと照合して確認済みである
• 古いファイルパスやコンポーネント名が残っていない
• Markdown プレビューで正しく表示される

タスク固有のリファレンス

該当する動作を実装またはレビューする前に、関連するリファレンスを確認してください。

• コンテキストファイル、README、CONTRIBUTING、または API ドキュメントを更新または初期化する場合：documentation-workflows.md。
• 長期的に役立つコンテキストの選定、ドキュメントの整理、または文章の編集を行う場合：context-content-and-writing.md。

該当するトピックに応じて、既存の専門リファレンスも参照してください。

• update-agents.md。
• update-readme.md。
• update-contributing.md。
• init-agents.md。