llmdocs

STARTER_CHARACTER = 📐

プロジェクトのドキュメントを更新する

担当する内容は2つです。

1. CLAUDE.md — 簡潔なプロジェクト概要（常に読み込まれます）
2. .llmdocs/ — コンセプトごとの詳細なドキュメント（必要に応じて読み込まれます）。ここのファイルはすべて永続的な設計ドキュメントです。

---

1. CLAUDE.md — 地図

範囲

プロジェクト内のすべてのCLAUDE.mdと.llmdocs/ディレクトリを見つけ、それぞれを更新します。 サブフォルダーの階層、範囲、境界づけられたコンテキストに注意してください。異なる階層のドキュメント間でコンセプトを混在させないでください。各CLAUDE.mdと.llmdocs/は、それぞれのディレクトリ階層とその下だけを対象とし、親階層の内容は扱いません。

ユーザーから具体的な指示や重点領域が示されている場合は、更新するドキュメントと強調する内容を決める際に、そのコンテキストを反映します。

コンテキストの収集

見つかった各CLAUDE.md/.llmdocs/の組み合わせについて、そのディレクトリを対象に次の手順を実行します。

1. 現在のCLAUDE.mdを読みます（存在する場合）。
2. ドキュメントを最後に更新してから何が変わったかを算出します。コミット済み、ステージ済み、未ステージ、未追跡の作業を含めます。

TARGET_DIR=<directory containing CLAUDE.md and .llmdocs/>

BASELINE=$(git log -1 --format=%H -- "$TARGET_DIR/CLAUDE.md" "$TARGET_DIR/.llmdocs/" 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の要約を読み、それをもとに差分全体を確認するか判断します。独自のコミットがないドキュメントでは、ルートコミットまで遡ります。そのため、中規模のリポジトリでは、差分全体がそのディレクトリの全履歴に及び、数千行になることがあります。要約が大きい場合は、差分全体の確認を省略し、変更されたファイルを直接読みます。

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

git status --shortを使うと、ステージ済み、未ステージ、未追跡のパスを一度に確認できます。未追跡ファイルは??と表示され、その内容はどの差分にも含まれないため、ファイルを直接読みます。.gitignoreに一致するファイルは、全体を通じて除外されます。

3. そのディレクトリ階層とその下のコードベースを調査します。
4. 関連する決定、変更、学びを把握するため、会話の履歴を確認します。
5. 差分と会話のコンテキストから変更内容を特定します。llmdocsは現在の状態を定める仕様であり、変更履歴でも、決定記録でも、過去の記録でもありません。llmdocsを記述する時点の仕様のみを記録し、過去の情報や選択を記録しないでください。

CLAUDE.mdの作成・更新

目標：500行未満。すべての行に価値を持たせます。

# <Name>

<1-2 line purpose of this directory/component>

## Stack

<bullet list: language, frameworks, key deps relevant to this level>

## Architecture

<key dirs and what they contain at this level>

## Commands

<build, test, lint, deploy — commands only>

## Conventions

<style, naming, patterns — only what prevents mistakes>

## Key Concepts

<domain terms, business logic Claude must know at this level>

## Docs

Detailed docs in `.llmdocs/`:

- @.llmdocs/architecture.md — <1-line description>
- @.llmdocs/data-model.md — <1-line description>

CLAUDE.mdのルール

• 冗長な説明はしません — Claudeが推測します
• .llmdocs/の内容を重複させません — 簡潔な説明を添えて参照するだけにします
• ## Docsセクションには、すべての.llmdocs/ファイルを1行の説明とともに記載する必要があります
• 既存のカスタム指示（gitのワークフロー、環境変数など）を保持します
• 既存の内容を削除する前に確認します
• 常に読み込むべきドキュメントには、@.llmdocs/filename.mdインポートを使います

---

2. .llmdocs/ — 領域

手順

1. 評価：コンテキストの収集で得た差分を使い、影響を受けるドキュメントを特定します
2. 特定：影響を受ける既存のドキュメント、または新しいドキュメントが必要かどうかを判断します
3. 提案：更新・作成するドキュメントと変更内容をユーザーに伝えます
4. 確認：書き込む前にユーザーの承認を得ます
5. CLAUDE.mdの更新：## Docsセクションに新しいドキュメントファイルが記載されていることを確認します

ドキュメントの更新に値する変更がない場合は、その旨を伝えて次に進みます。

場所

既存のCLAUDE.mdで指定されているパスを使います。指定がなければ、対象ディレクトリ階層の.llmdocs/を使います。CLAUDE.mdと.llmdocs/は、プロジェクト内のどのディレクトリ階層にも配置できます。

構成

フラットな構成とし、コンセプトごとにファイルを1つ用意します。最初の6ファイルは必須で、常に存在する必要があります。追加のコンセプトファイルは必要に応じて作成します。

.llmdocs/
  architecture.md    # Components, interactions, data flow (required)
  api.md             # Endpoints, request/response, authentication, authorization (required)
  data-model.md      # Schema, models, relationships (required)
  deployment.md      # Deploy process, environments (required)
  ops.md             # Maintenance, operations, runbooks (required)
  security.md        # Trust boundaries, secrets handling, authn/authz, threat model (required)
  <concept>.md       # Domain-specific as needed

ドキュメントファイルの形式

# <Concept>

<1-line purpose>

## <Section>

<content: headers, tables, code blocks — no prose paragraphs>

.llmdocs/ ルール

• 1 ファイルあたり最大 500 行です。超える場合は分割してください
• 必要に応じて、行番号を含むファイルパスを記載してください（src/auth/login.ts:42）
• 既存のドキュメントは一から書き直さず、段階的に更新してください
• ドキュメントが正確で、最近の変更の影響を受けていない場合は、変更しないでください
• 網羅性より正確性を優先してください。コードで検証できる内容のみを記載してください

---

3. 出力の概要

実行後、次の内容を出力してください。

• 作成または変更したファイル
• CLAUDE.md の変更内容（追加・更新・削除したセクション）
• 更新または作成したドキュメント（または「ドキュメントの変更は不要」）