project-docs

プロジェクトドキュメント

PHP/Laravel および Node/TypeScript/React プロジェクト向けの、ドキュメントのライフサイクル全体を網羅します。フォルダー構成、命名規則、必須ファイル、コンテンツの品質（AI による粗雑な生成物の検出を含む）、蓄積された不要ファイルの整理、ライフサイクルを扱う、6 カテゴリにわたる 25 のルールが含まれています。ブートストラップモード（新しいプロジェクトにドキュメントをセットアップ）、監査モード（不足、古さ、肥大化、不要なものを特定）、リファレンスモード（規約を参照）に対応しています。

メタデータ

• バージョン： 1.0.0
• 対象範囲： PHP / Laravel および Node / TypeScript / React プロジェクト
• ルール数： 6 カテゴリにわたる 25 のルール
• ライセンス： MIT

このスキルの使い方 — 3 つのモード

モード 1：ブートストラップ（新しいプロジェクト／ドキュメント不足）

ユーザーが「ドキュメントをセットアップして」「このプロジェクトに必要なドキュメントは何？」と尋ねた場合、または新しいプロジェクトを始める場合は、次のブートストラップ手順に沿って進めます。

1. プロジェクトの種類を判定する（Laravel？React？両方？）— composer.json、package.json、artisan バイナリを確認します
2. 既存のドキュメントを一覧化する — 各 .md ファイルの場所と最終更新日を列挙します
3. 不足箇所を特定する — 必須ファイルのチェックリストと照合し、不足しているものを報告します
4. フォルダー構成を提案する — プロジェクトの規模に応じて、サブフォルダー（architecture/、adr/、guides/、runbooks/、archive/）を含む docs/ を提案します
5. テンプレートのひな型作成を提案する — README、CHANGELOG、LICENSE、CONTRIBUTING、SECURITY、ADR-0001 を、ユーザーの承認を得て生成します。自動作成はしません
6. CI ゲートを提案する — markdown-lint、リンク切れチェッカー（lychee）、PR 作成時の CHANGELOG 更新の必須化

モード 2：監査（既存プロジェクトの整理）

ユーザーが「ドキュメントを監査して」「Markdown を整理して」「何を削除すべき？」と尋ねた場合は、分類した台帳を作成します。

リポジトリ内の各 .md ファイルについて、次のように分類します。

• KEEP — 必須で、最新のファイル
• UPDATE — 必須だが古くなっているファイル（例：README の内容が現在のセットアップと食い違っている）
• ARCHIVE — 置き換えられているが、履歴として役立つファイル — docs/archive/<year>/ に移動します
• DELETE — AI が生成した計画ファイル、空のひな型、重複ファイル、孤立した下書き
• MOVE — 場所または名前が適切でないファイル（例：ルートにある MyArchitectureNotes.md → docs/architecture/overview.md）

出力形式：

## Documentation Audit Ledger

| File | Last modified | Verdict | Reason | Action |
|------|---------------|---------|--------|--------|
| PLAN.md | 2026-02-14 | DELETE | AI-generated plan, no longer referenced | rm PLAN.md |
| README.md | 2024-08-01 | UPDATE | Setup steps reference removed Vite v3 | Update install section |
| docs/old-architecture.md | 2024-11 | ARCHIVE | Superseded by docs/architecture/overview.md | mv to docs/archive/2024/ |
| MyNotes.md | 2025-09 | DELETE | Personal notes; not project docs | rm MyNotes.md |

## Summary
- KEEP: X files
- UPDATE: Y files (top priority: ...)
- ARCHIVE: Z files
- DELETE: N files
- MOVE: M files

自動削除は絶対にしないでください。 必ず最初にユーザーの承認を求めてください。

モード 3：リファレンス（規約の参照）

ユーザーが「これはどう命名すべき？」「どこに置くべき？」と尋ねた場合、またはコードレビューの文脈でこのスキルに言及した場合は、rules/ 内の該当するルールを参照します。

適用する場面

次の場合にこのスキルを参照します。

• 新しい Laravel または Node/React プロジェクトを始める際に、ドキュメントの基準が必要な場合
• Markdown ファイルが雑然としている、または AI 生成物で散らかっているプロジェクトを引き継ぐ場合
• docs/ フォルダーの構成を設定する場合
• 新しいドキュメントファイルに名前を付ける場合
• PLAN.md / TODO.md / IMPLEMENTATION-SUMMARY.md を削除するか判断する場合
• Markdown の品質を確認する CI チェックを追加する場合
• ドキュメントを追加または変更する PR をレビューする場合
• 四半期ごとの「ドキュメント整理」を行う場合

ステップ 1：プロジェクトの種類を判定する

具体的な推奨を行う前に、必ずプロジェクトの技術スタックを確認してください。 ブートストラップと命名に関するガイダンスは、技術スタックによって多少異なります。

シグナル	プロジェクトの種類	備考
composer.json + artisan	Laravel（PHP）	README には composer install、php artisan migrate、.env.example を記載します
package.json のみ	Node / TypeScript / React	README には npm install、.nvmrc、ビルドスクリプトを記載します
両方ある	Laravel + Inertia + React	README では PHP と Node の両方のセットアップ手順を扱います

ルールはほとんどが技術スタックに依存しません。README の形式、ADR の構成、命名規則は、どのプロジェクトにも適用できます。

優先度別のルールカテゴリ

優先度	カテゴリ	影響度	プレフィックス
1	構成	CRITICAL	structure-
2	命名	CRITICAL	naming-
3	必須ファイル	HIGH	essential-
4	品質	HIGH	quality-
5	整理	HIGH	cleanup-
6	ライフサイクル	MEDIUM	lifecycle-

クイックリファレンス

1. 構成（重要）

• structure-root-files — README、CHANGELOG、LICENSE など、リポジトリのルートに置くファイル
• structure-docs-folder — ルートファイル以外のすべてを置く場所としての docs/
• structure-subfolders — 推奨される docs/ の構成：architecture/、adr/、guides/、runbooks/、archive/

2. 命名規則（重要）

• naming-root-files — 慣例的なルートファイルには UPPERCASE.md を使用
• naming-docs-files — docs/ 内のファイルには kebab-case.md を使用
• naming-adr-files — 連番のプレフィックスを付ける：0001-record-architecture-decisions.md
• naming-anti-patterns — 日付、MyNotes.md、tmp/draft/final のようなマーカーは使用しない

3. 必須ファイル（優先度高）

• essential-readme — すべてのプロジェクトに、目的、インストール方法、使用方法、ライセンスを記載した README が必要
• essential-changelog — Keep a Changelog 形式を使用し、リリースごとにエントリーを1つ記載
• essential-license — リポジトリのルートに LICENSE ファイル（または LICENSE.md）を置く
• essential-contributing — 外部のコントリビューターを受け入れる場合は CONTRIBUTING.md を用意
• essential-security — 脆弱性の報告ポリシーを記載した SECURITY.md を用意

4. 品質（優先度高）

• quality-conciseness — 冗長な部分を削る。長さは美徳ではなくコスト
• quality-ai-slop — AI 生成コンテンツにありがちなパターン（埋め草、結びの言葉、ありきたりな称賛）を検出
• quality-headings — H1 は1つにし、レベルを飛ばさず、説明的な見出しにする
• quality-code-blocks — 言語タグを付け、コピーして使えるコマンドを記載し、言語タグのないコードブロックは使わない
• quality-links — 説明的なリンクテキストを使い（「ここをクリック」は避ける）、相対パスを使用し、リンク切れがないようにする

5. 整理（優先度高）

• cleanup-ai-junk — AI が生成した計画・要約ファイルを検出して削除
• cleanup-duplicates — 複数のファイルに同じ内容がある場合は、統合するか重複分を削除
• cleanup-orphans — どこからもリンクされていない .md ファイルは、アーカイブするか削除
• cleanup-empty-stubs — TBD / TODO / プレースホルダーだけのファイル

6. ライフサイクル（優先度中）

• lifecycle-freshness — アーキテクチャ文書に「最終確認日」を記載
• lifecycle-archive — 古くなった文書は docs/archive/<year>/ に移動
• lifecycle-adr-process — ADR の作成条件とライフサイクル（提案 → 承認 → superseded）
• lifecycle-changelog-discipline — 変更を加える PR と同時に CHANGELOG のエントリーを追加

必須のパターン

標準的なフォルダー構成

.
├── README.md                      # required
├── CHANGELOG.md                   # required from first release
├── LICENSE                        # required
├── CONTRIBUTING.md                # if external contributors
├── SECURITY.md                    # if internet-facing
├── CODE_OF_CONDUCT.md             # if open source community
├── .github/
│   └── CODEOWNERS                 # team ownership
└── docs/
    ├── architecture/
    │   ├── overview.md
    │   └── data-model.md
    ├── adr/
    │   ├── 0001-record-architecture-decisions.md
    │   ├── 0002-choose-mysql-over-postgres.md
    │   └── 0003-adopt-inertia-for-spa.md
    ├── guides/
    │   ├── getting-started.md
    │   ├── deployment.md
    │   └── local-development.md
    ├── runbooks/
    │   ├── deploy-production.md
    │   └── incident-response.md
    └── archive/
        └── 2024/
            └── old-architecture-notes.md

ファイル命名の概要

✓ README.md, CHANGELOG.md, LICENSE, CONTRIBUTING.md, SECURITY.md
✓ docs/architecture/overview.md
✓ docs/adr/0007-cache-strategy.md
✓ docs/guides/deployment.md
✓ docs/archive/2024/q3-launch-plan.md

✗ Readme.md, Changelog.md          (use UPPERCASE for conventional root files)
✗ docs/Architecture/Overview.md    (use kebab-case in docs/)
✗ docs/Notes-2025-09-14.md         (no dates in filenames)
✗ MyArchitectureThoughts.md        (no first-person, no PascalCase)
✗ PLAN.md, TODO.md, TEMP.md        (use issue tracker for transient state)
✗ FINAL-deployment-guide-v2.md     (no draft/final/v2 markers)

CI：Markdown を正確に保つ

# .github/workflows/docs.yml
- name: Lint markdown
  uses: DavidAnson/markdownlint-cli2-action@v23

- name: Check links
  uses: lycheeverse/lychee-action@v2
  with:
    args: --no-progress --exclude-mail './**/*.md'

使用方法

詳しい規約と例については、各ルールファイルを参照してください。

rules/structure-root-files.md
rules/naming-adr-files.md
rules/essential-readme.md
rules/cleanup-ai-junk.md
rules/lifecycle-archive.md

各ルールファイルには、次の内容が含まれています。

• メタデータ（タイトル、影響度、タグ）を含む YAML フロントマター
• 重要である理由の簡潔な説明
• 不適切な例（アンチパターン）
• 適切な例（規約）
• 該当する場合は、検出・適用に関するガイダンス

参考資料

• Keep a Changelog
• Semantic Versioning
• Architecture Decision Records (ADR)
• Diátaxis — ドキュメントフレームワーク
• Choose a License
• Markdownlint
• Lychee — リンクチェッカー

完全版のドキュメント

すべてのルールを展開した完全版ガイド：AGENTS.md