readme

STARTER_CHARACTER = 📓

ドキュメントの作成

現在の会話コンテキストとフォルダーの内容に基づいて、Markdown コンテンツを作成します。

README は人間のユーザー向けの現状仕様であり、変更履歴でも、意思決定記録でも、過去の記録でもありません。README の執筆時点での仕様のみを記録し、過去の情報や選択した内容は記録しないでください。

関連スキル

• Markdown のルールと構文には md-syntax スキル（/md-syntax、$md-syntax）を使用します
• 執筆規約と文章スタイルには md-style スキル（/md-style、$md-style）を使用します
• 執筆後、md-lint スキル（/md-lint、$md-lint）を使用してファイルをフォーマットし、Lint を実行します

対象範囲

プロジェクト内の README.md をすべて見つけ、それぞれを更新します。 フォルダーの内容として扱うのは README と同じ階層以下（同じ階層の項目とサブフォルダー）であり、親階層は含めません。 サブフォルダーの階層、対象範囲、境界づけられたコンテキストに注意してください。階層の異なるドキュメント間で概念を混在させないでください。各 README は、そのディレクトリ階層以下のみを対象とし、親階層の内容は扱いません。

ユーザーが特定のガイダンスや重点項目を提示した場合は、ドキュメントで何を強調するかを決める際にそのコンテキストを反映してください。

コンテキストの収集

見つかった README ごとに、そのディレクトリを対象として次の手順を実行します。

1. 現在の README を読みます（存在する場合）。
2. 最後に変更されてから何が変わったかを確認します。コミット済み、ステージ済み、ステージされていない変更、未追跡の作業を含めます。

TARGET_README=<path to the README being updated>
TARGET_DIR=$(dirname "$TARGET_README")

BASELINE=$(git log -1 --format=%H -- "$TARGET_README" 2>/dev/null)
[ -z "$BASELINE" ] && BASELINE=$(git rev-list --max-parents=0 HEAD 2>/dev/null)
HEAD_SHA=$(git rev-parse --verify -q HEAD)

if [ -n "$BASELINE" ] && [ "$BASELINE" != "$HEAD_SHA" ]; then
  git log --oneline "$BASELINE"..HEAD -- "$TARGET_DIR"
  git diff "$BASELINE" --stat -- "$TARGET_DIR"
  git diff "$BASELINE" -- "$TARGET_DIR"
elif [ -n "$HEAD_SHA" ]; then
  git show --stat HEAD -- "$TARGET_DIR"
  git diff HEAD --stat -- "$TARGET_DIR"
  git diff HEAD -- "$TARGET_DIR"
fi

git status --short -- "$TARGET_DIR"

--stat は -- より前に指定する必要があります。後ろに置くと、git はこれをパス指定として解釈し、要約ではなく完全な差分をそのまま表示します。

まず --stat の要約を読み、それを基に完全な差分を確認するかどうかを判断します。README 自体にコミットがない場合は、ルートコミットまで遡ります。そのため、完全な差分がディレクトリ内の全履歴、つまり中規模のリポジトリでは数千行に及ぶことがあります。要約が大きい場合は、完全な差分を省略し、変更されたファイルを直接読みます。

差分には ..HEAD がないため、ベースラインから作業ツリーまでの範囲が含まれ、ステージ済みとステージされていない編集の両方を含みます。この分岐では、README 自体にコミットがある場合、ない場合、リポジトリにルートコミットしかない場合、コミットがまったくない場合の 4 つの状態を扱います。これらがないと、ベースラインが空、または HEAD と同じ場合にすべてのコマンドが何も返さず、このスキルはドキュメントに記載する内容がないと誤って判断します。

git status --short は、ステージ済み、ステージされていない、未追跡のパスをまとめて表示します。未追跡ファイルは ?? と表示され、その内容はどの差分にも含まれないため、ファイルを直接読みます。.gitignore に一致するファイルは、すべての処理から除外されます。

3. そのディレクトリ階層以下のコードベースを調査します。
4. 関連する意思決定、変更、学びがないか、会話履歴を確認します。
5. 差分と会話のコンテキストを使って、更新が必要なセクションを特定します。コードとドキュメント、ドキュメントとコードの両方を照合します。

README の更新が必要な変更がなければ、その旨を伝えて次に進みます。

README.md の構成

README.md のセクションの順序と内容です。各セクションには対象プロジェクトの内容を記載します。プロジェクトに該当する内容がないセクションは省略します。

• # タイトルと、5 文以内の概要
• 任意の画像または動画
• ## アーキテクチャ — コンポーネントを箇条書きで示し、それぞれの役割を記載
• ## 前提条件 — 必要なアカウント、キー、認証情報、ツール、ランタイム、CLI と、それぞれが必要な理由
• ## プロジェクト構成 — ファイルは含めず、フォルダーのみを記載し、それぞれの目的を 1 行で説明
• ## インストール — インストールするコマンド
• ## 使い方 — 実行するコマンド
• ## テスト — プロジェクトにテストがない場合は省略

500 行未満を目指します。README がそれより長くなる場合は、説明するコードの隣にあるネストした README に詳細を移します。

形式

# Title

Brief overview. No more than five sentences.


<img src="demo.png" alt="Demo" width="800"/>

## Architecture

High level components and purpose

- Component - purpose
- Component - purpose

## Prerequisites

- Prerequisite - description and reason (accounts, keys, credentials, tools, runtimes, CLIs)

## Project Structure

Show folder structure. Don't include files.

```text
project/
├── src/
│   ├── component-a/     # purpose - see src/component-a/README.md
│   └── component-b/     # purpose - see src/component-b/README.md
├── scripts/             # purpose
└── tests/               # purpose
```

## Installation

```bash
# how the project is installed
<install command>
```

## Usage

```bash
# how the project is run
<run command>
```

## Testing

```bash
# how the tests are run
<test command>
```