0x0w1/jig

README

このスキルは、リポジトリの実際の状態から、そのリポジトリの README.md を作成または更新するために使用します。

手順

1. リポジトリをスキャンする:
   • マニフェストファイルとビルドファイル: pyproject.toml, package.json, Cargo.toml, go.mod, Makefile, ロックファイル。
   • エントリーポイント、CLI引数定義、スクリプト、サービス設定 (Dockerfile, docker-compose*.yml)。
   • docs/ 下の既存のドキュメントとコード内の使用例。
2. プロジェクトタイプを分類する: CLIツール、ライブラリ、サービス/アプリ、または その他。タイプにより、以下でプロファイルが設定されていない場合のセクションレイアウトが選択されます。
3. 下記のプロファイル契約に従ってREADMEプロファイルを確定します。解決されたプロファイルは、このリポジトリの汎用デフォルトを上書きします。何も解決されない場合は、プロファイルを提案し、どちらにせよ続行します。
4. 現在の状態に基づいて分岐する:
   • README.md がない場合 → 作成パス: 下記のセクションレイアウトでREADMEをドラフトします。
   • README.md が存在する場合 → 更新パス: README内のすべての検証可能な主張（コマンド、オプション、ファイルパス、リンク、機能ステートメント）をリポジトリと照合して確認します。不一致をドリフトリストに収集し、リストを報告してから修正を適用します。まだ正確なセクションはそのままにします。
5. 下記の正確性ルールを、書かれるすべての行に適用します。
6. 下記の圧縮ルールから圧縮パスを実行する:
   • 作成パス: ドラフト中に適用します。まだ何も公開されていないため、提案するものはありません。
   • 更新パス: 重複と誇張を提案にまとめます — 各事実、それが繰り返されている場所、そしてそれを保持する詳細ドキュメントに名前を付けます — そして、何かを移動する前に確認を求めます。ユーザーが拒否した場合でも提案を報告します。
7. 変更をマージする:
   • リポジトリに develop-task-flow スキル（またはインストール済みの jig-develop-task-flow）がある場合、それに従います: chore/<slug> ブランチ、docs: コミットでのスカッシュマージ、その後 develop にプッシュ。
   • それ以外の場合は、現在のブランチに通常のコミットを提案します。

プロファイル契約

同じプロジェクトタイプの2つのリポジトリでも、READMEの書き方は異なります: あるものは翻訳ミラーを保持し、別のものはインストールをガイドに移動し、3つ目は、そのコントリビューターがすでに従っているテーブル規則を持っています。これらは、リポジトリをスキャンして確認できる事実ではなく、決定事項であるため、一度記録され、後の実行ごとに読み込まれます。

プロファイルは次の順序で解決します:

1. JIG_README_PROFILE 環境変数。
2. git config --local --get jig.readmeProfile。
3. .jig/readme.md。

プロファイルが解決された場合、そのリポジトリのセクションレイアウトと言語ルールを上書きします。プロファイルが言及していないものは、これらのデフォルトにフォールバックします。プロファイルを読み、それに従い、報告書にその名前を記載します。

何も解決されない場合、スキャン結果からプロファイルをドラフトして提案します: 分類されたタイプ、リポジトリがすでに使用している言語、ミラーの有無、現在のREADMEが示唆するセクション順序、およびどの詳細ドキュメントがすでにオーバーフローを保持しているか。ユーザーが承認した場合のみ .jig/readme.md を書き込みます。ユーザーが拒否するか回答しない場合は、汎用デフォルトで続行し、その旨を伝えます — プロファイルがないことは通常の状態であり、ブロッカーではありません。

このファイルは決定事項のみを記録します。しきい値やチェックリストは含まれません。READMEの品質は、このスキルがリポジトリを前にして行う判断に委ねられます。

# README Profile

> 根拠: <決定方法>, <YYYY-MM-DD>

## 言語

正規: `README.md` (英語)。ミラー: `README.ko.md` (韓国語)、同じタスク内で更新。

## セクション

タイトルとリンク行、これは何か、クイックスタート、スキル、ドキュメント、ライセンス。

## 詳細ドキュメント

インストールオプション → `docs/installation.md`。ロードマップと設計記録 → `docs/roadmap.md`、ドキュメントホームからのみリンク。

## 規則

識別子テーブルは説明セルを1節に保ちます。コントリビューターコマンドは `<details>` ブロック内に配置します。

セクションタイトルが契約であり、その下の散文はリポジトリ独自のものです。これらのタイトルが存在する前に書かれたプロファイルでも、それらを使用していれば正しく読み取れます。

セクションレイアウト

必須セクション（順序通り）:

1. タイトルと1行の説明。
2. はじめに: プロジェクトの目的と存在理由。
3. インストール。
4. 使い方。

プロジェクトタイプによる追加:

• CLIツール: コマンドとオプションのテーブル。
• ライブラリ: サンプルコード付きのAPI概要。
• サービス/アプリ: 実行方法（開発環境と本番環境）と必要な環境変数。

オプション: ドキュメントリンク、ライセンス。

レイアウトルール

• 識別子（スキル名、コマンド、オプション、パス）にはテーブルが適しています。そのような名前を壊すのは列間の幅の比率です: GitHubは内容に応じて列サイズを調整するため、識別子列よりも数倍長い説明列は識別子を圧縮して途中で折り返させ、読者は存在しない名前を見ることになります。
• 説明セルは識別子とほぼ同じ長さ（約1節）に保ちます。説明が長くなる場合は、短くするか、リストに移動します: - **\name`** — 説明`。
• 説明内での折り返しは想定内であり、対処は不要です。

圧縮ルール

READMEは、読者がプロジェクトを使用することを決定する前に読まれます。その中のすべてがその注意を競合するため、長さは症状です: 長いREADMEは、ほとんどの場合、多くのことを言っているプロジェクトではなく、1つの事実が複数の場所に書かれているものです。

削除せずに移動する。 同じ事実が複数の場所に現れる場合、読者が最初にたどり着く場所に保持し、残りはそれをすでにカバーしている詳細ドキュメントに移動します。存在しない場合のみドキュメントを作成します。何も失われません。READMEは自己反復を停止します。ヒットすべき行数はありません — 真に必要なAPI例があるライブラリのREADMEは長すぎず、同じことを2回言っている短いREADMEも依然として間違っています。

読者が得られるものから始める。 はじめには、どの機能が存在するかではなく、何が容易になるかを述べます。「マージ時に段階的なリリーストレーラーを記録する」は機能です。「バージョンがマイナーだった理由を再構築する必要がなくなる」は読者が得られるものです。証拠が強い順に主張を並べ、周囲の散文もその順序でリストします — 段落とその箇条書きで異なる優先順位を暗示してはいけません。

リポジトリが裏付けられるものだけを主張し、いつ適用されるかを述べる。 リポジトリが実証できない主張は、和らげずに除外します。価値が現れる条件を明記し、その条件外の読者は後で発見するのではなく、プロジェクトを迅速に除外できるようにします。

インストール前に読まれないものは削除する。 ロードマップ、設計記録、方向性ノートは、プロジェクトが自分自身のために保持するものです。READMEではなく、ドキュメントホームからリンクします。

コントリビューター向け資料は折りたたむ。 ビルド、再生成、検証コマンドは、すでにリポジトリをクローンした人向けです。<details> ブロックまたはコントリビューティングドキュメントに配置します。

1つの値だけが異なるブロックは統合する。 プラットフォームやターゲットごとに引数だけが異なる個別のコマンドブロックは、その引数が名前付けられた1つのブロックになります。

冒頭を超える方法を読者に提供する。 READMEに約4つ以上のセクションがある場合、タイトルの下に1行のリンク行を配置し、戻ってきた読者が目的のセクションに直接ジャンプできるようにします。

正確性ルール

• リポジトリに対して検証されたインストールコマンドと実行コマンドのみを記述します: スクリプト、マニフェスト、またはロックファイルがそれらを示している必要があります。
• リンクされたすべてのファイルパスが存在することを確認します。
• リポジトリに含まれていない機能、バッジ、統合については説明しません。
• 主張が検証できない場合は、それを除外し、代わりに報告します。

安全ルール

• .jig/readme.md は、ユーザーが提案を承認した後にのみ書き込まれ、通常のREADME更新の副作用として決して書き込まれません。
• 既存の .jig/readme.md は、明示的な確認なしに上書きされることはありません。変更を提案し、何を置き換えるかを明記します。
• .jig/ 下のその他のものには触れません。version-rubric が .jig/versioning.md を所有します。
• 公開されたREADMEは、黙って再構成されることはありません。圧縮パスは提案し、待機します。
• 無関係なユーザーの変更は保持されます。

言語ルール

• 既存のREADMEはその言語を維持します。
• 新しいREADMEは、リポジトリがドキュメントにすでに使用している言語で記述され、デフォルトは英語で、技術用語はバッククォートで囲みます。
• ユーザーからの明示的な言語要求は、両方を上書きします。

報告

• プロジェクトタイプと実行されたパス（作成か更新か）。
• READMEプロファイル: パスとソース、または提案して拒否された、またはなしで汎用デフォルトで実行中。
• 更新パスの場合: ドリフトリストと修正内容。
• 圧縮提案: 複数の場所で繰り返されている各事実、移動先、およびユーザーが承認したかどうか。
• 検証できずに除外された主張。