ドキュメント同期
コードとその文書は、同じコミット内で一緒に変更されます。間違った文書は、文書がないことよりも悪いです。
文書が間違ってしまう3つの方法
- 古くなっている。 文書が古い動作、名前、またはコマンドを説明したままになっている。
- 不足している。 新しい動作、新しいコマンド、または新しい設定に文書がない。
- 重複している。 同じ事実が複数の場所にある。後で一方が変更されても、もう一方が変更されない。
手順
- 何が変更されたかを確認する。
git diff --cached --stat git diff --stat - リポジトリ独自のルールを見つける。
CLAUDE.md、CONTRIBUTING.md、docs/README.mdを読む。どの文書がどのトピックを担当するかが書かれていれば、それに従う。これは手順3より優先される。 - 各変更をその担当文書にルーティングする。
resources/doc-routing.mdを使用する。1つの事実には1つのホームがある。他の文書はそこにリンクする。 - 古い参照を見つける。 名前を変更または削除した場合（関数、フラグ、エンドポイント、設定、ファイルパス、コマンド）：
git grep -n '<古い名前>' - 編集する。 コード変更によって間違った、または不完全になった箇所のみを変更する。関連のないセクションを書き換えない。明確な表現のために、
simple-englishスキルがインストールされていればそれを使用する。 - 一緒にコミットする。 文書の変更をコードと一緒にステージングする。それらを後続のPRに入れない。
- 報告する。 変更した文書のリストを作成する。変更が必要なかった場合は、一行でその理由を述べる。例：「ドキュメント変更なし：内部リファクタリングであり、動作、コマンド、設定に変更はありません。」
担当文書が明確でない場合
ユーザーに質問する。質問を避けるために新しい文書を作成しない。
有用な判断基準：それは現在の状態についての事実（設定、バージョン、ステータス）ですか？ それはリファレンス文書またはステータス文書に属します。それは手順（誰かが従う手順）ですか？ それはその手順を担当するガイド、ランブック、またはスキルに属します。
仕様が優先される
リポジトリに SPEC.md（engineering:spec-writing を参照）または .gener8v/specifications/ 以下のgener8v仕様がある場合、それらが意図された動作を定義します。
- 変更が仕様の通りである場合、仕様の編集は不要です。
- 変更が仕様に矛盾する場合、停止します。ユーザーに伝えます。まず、その所有者を通じて仕様を変更します：
SPEC.mdにはengineering:spec-writing、パイプライン仕様にはgener8v:specification。コードに合わせて仕様を黙って編集しないでください。
パイプライン文書
.gener8v/ 以下のファイルは手動で編集しないでください。gener8vパイプラインスキルがそれらを作成および更新します。
関連スキル
engineering:documentation-bootstrap：段落だけでなく文書全体が不足している場合。engineering:github-pr-merge：PRの前にこのチェックを実行します。engineering:github-release：このスキルが最新に保つCHANGELOGのUnreleasedセクションを読み取ります。