impa は何をしますか？
開発者またはエージェントが行動に移せる、コードと一致したテクニカルドキュメントを作成します。目標は、読者のタスクに対して正確で、最新かつ完全であり、見つけやすく、動作する例があり、明確で直接的な、必要以上に長くないドキュメントを提供することです。
1ラウンドは、ユーザーが依頼した1つの作業単位です。すべてのラウンドは、依頼がなくてもレビューで終了します。
ステップ
1. プロジェクトを読む
何かを書く前に、既存のものを読み込みます：
- プロジェクトに存在する場合、
.impa/plan.md - ドキュメント：README、
docs/、サイトのソースと設定、チェンジログ、コントリビューティングガイド、指示ファイル。ジェネレーターやCIのドキュメントチェックがあればメモします。 - 読者が触れるコード：エントリポイント、コマンドパーサー、設定スキーマ、環境変数、エラーメッセージ、公開API、マニフェスト。
どのような種類のプロジェクトか（ライブラリ、CLI、サービス、エンドユーザーアプリ、内部ツール）を把握し、エージェントが読むかどうかも含めて誰がドキュメントを読むのかを理解します。プロジェクトが答えられないことだけをユーザーに尋ねます。
プロジェクトのドキュメントツールに従います。何もない場合は、プレーンなMarkdownファイルを使用します。
2. ドキュメントタイプを選択する
reference/doc-types.md を読んでください。この種のプロジェクトに必要な行から始め、トリガーが発火した場合のみトリガー行を追加し、そこで止めます。1ページは1つの役割を果たします。ユーザーが1ページを依頼した場合は、そのページだけを書き、他は追加しません。
ユーザーが依頼していないドキュメントの再構成は行いません。
3. 計画を維持する
プロジェクト内の .impa/plan.md を作成または更新します。これは次のラウンドが読み込むものです：
# ドキュメント計画
プロジェクトの種類: CLI
読者: CLIを使用する開発者、およびこのリポジトリで作業するコーディングエージェント
ドキュメントツール: プレーンMarkdown
例の証明レベル: rung 3
## ページ
| ページ | タイプ | 役割 | 読者 |
| --- | --- | --- | --- |
| README.md | README | 何であるかと開始方法を説明する | 初めて訪れる人 |
## ハウススタイル
見出しのケース、タスク見出しの形式、短縮形、「私たち」、プレースホルダーの形式、`$` プロンプト。プロジェクトが既に使用しているものに合わせます。
## 担当者待ち
## 教訓
計画にはページと選択が保持されます。レビュアーがこれを読むため、その理由は計画に含めないでください。
4. ルールに従って書く
プロジェクトにドキュメントがある場合は、review/round.md の「編集前のコピー」にあるように、まずそれらをコピーします。ラウンドの差分はそのコピーから生成されます。
最初に reference/principles.md を読み、次に作業に必要なものを読みます。小さな編集では、必要なものだけを読みます。
| 読むもの | 条件 |
|---|---|
| structure.md、wording.md、leave-out.md | 書くすべてのページ |
| examples.md | コードを含むページ |
| accuracy.md | 検証前、および生成リファレンスを設定するとき |
| agent-readers.md | 指示ファイル、スキル、ツールの説明、エージェントが取得するサイト |
audit.md と sources.md は作成用ではありません。前者は impa audit のビルドリストであり、後者は引用を保持します。
これらのルールが存在する理由となる落とし穴：
- 最初に答える。 ページは、何をするかを一文で始めます。次に一般的なケース、そしてエッジケースです。
- 短いとは、無駄な言葉がないことであり、それ以外ではない。 前置き、歴史、繰り返しを削除します。デフォルト値、制限、エラー、前提条件、例は保持します：
leave-out.mdの保持リストは、それらを削除すると読者に害があるため存在します。 - 生成できるものは生成する（A1）。 ツールがコードから生成できるフラグ、シグネチャ、デフォルト値、スキーマは手で入力すべきではありません。プロジェクトのジェネレーターを使用するか、役立つジェネレーターがあることをユーザーに伝えます。
- 各事実に対して1つの情報源。 一度だけ記述し、リンクします。
- ハウススタイルに合わせる。 一貫性が最優先です。このルールセットの表現の選択は、スタイルが定義されていないプロジェクトのデフォルトです。
- フロントマター： ドキュメントツールが許可する場合、docs フォルダ内のページに
typeを付けます（T2）。README、チェンジログ、指示ファイルにはフロントマターを決して追加しないでください。GitHubは最初の文章の上に表として表示し、ツールはそれらのファイルを全体として読み込みます。 - 指示ファイルには、エージェントがリポジトリから判断できないことだけを保持する（G1）。 生成された指示ファイルは、コミットされる前に人間が編集する必要があります（G11）。その旨をユーザーに伝えます。
- 決して何も発明しない。 見つからない事実は、書かない文です。スタブ、空の見出し、
TODOを残さないでください（T4）。値なしではページが機能しない場合は、API_URL_TODOなどの明白なセンチネル値を使用し、計画の 担当者待ち に追加します。
5. コードに対して検証する
ページが主張する各項目を、それが説明するコードに対して1つずつチェックします。安全な場合は実行も行います。なぜなら、読むだけでは実行でわかることが見逃される可能性があるからです。
| ページが主張すること | チェック対象 |
|---|---|
| コマンド、サブコマンド、フラグ | パーサーのソース、および実際の --help |
| パスまたはファイル | ツリー。ただし、ページが読者によって作成されることを示している場合は除く |
| デフォルト値、制限、単位、順序、副作用 | それを設定するコード行。ヘルプテキスト、コメント、古いドキュメントは除く |
| 環境変数、設定キー | コードがそれを読み込む場所 |
| エラーメッセージ | ソース内の正確な文字列 |
| バージョン、サポート対象プラットフォーム | マニフェストまたはCI設定 |
| API名、シグネチャ、戻り値 | 定義 |
| 例 | プロジェクトの証明レベル（examples.md）に従ってコンパイルまたは実行する |
| インストール、クイックスタート、チュートリアル | クリーンな状態から、テンポラリフォルダ内で各ステップを実行する |
実際のデータ、実際の資金、共有システムに影響を与えるものは決して実行しないでください。実行しなかったことを報告します。
既存のドキュメントは証拠になりません。たとえ保持するものであっても同様です。検証できない主張は削除するか報告し、信用して残したままにしないでください。
ドキュメントとコードが矛盾する場合、コードがバグである可能性があります。コードが実際に行うことを書き、そのことをユーザーに伝え、ユーザーが依頼しない限りコードは変更しません。
6. 監査を実行する
impa audit --dir <project>
実際の問題を修正します。コマンドが失敗した場合、またはバイナリに audit がない場合は、監査が実行されなかったことをユーザーに伝え、続行します。クリーンな監査はほとんど証明になりません。名前が存在することを確認できるだけで、その周りの文が真実であることは確認できません。クリーンな実行を得るために値を偽装しないでください。
7. ラウンドをレビューする
依頼がなくても review/round.md に従います。レビューは初回はドキュメントセット全体をカバーし、その後は差分とそれが触れる範囲をカバーします。バックグラウンドで impa review を通じて実行されます。
このラウンドについてユーザーが明示的にスキップを指示した場合のみスキップし、スキップされたことを報告します。レビューが実行される前にドキュメントを完了と呼んではいけません。
review/method.md や review/checklist.md は読み込まないでください。これらを読み込むのはレビュアーのみです。
8. 報告する
ユーザーに以下を伝えます：
- 何を書いたか、または変更したか、選択したドキュメントタイプ。
- 検証できなかったもの、または実行しなかったもの。
- ドキュメントとコードが矛盾した箇所と、それに対して行った対応。
- レビュー：その判定、見つかった問題、修正した内容、未解決の事項、対応できる人、コスト。
判定が「人間の対応が必要になるまで出荷不可」の場合は、その言葉で始めます。
ユーザーが依頼しない限り、コミット、プッシュ、公開は行いません。
9. 学ぶ
ユーザーが何かを修正した場合、またはラウンドでこのプロジェクトの落とし穴が明らかになった場合、それを .impa/plan.md の 教訓 に追加します。ここでのルールがすべてのプロジェクトに対して間違っている場合は、その旨をユーザーに伝えます。修正は1つのプロジェクトの計画ではなく、このスキルに属します。