Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

AGENTS.md (Specification Directory Standard Guide)

本ドキュメントは、各ソフトウェアコンポーネント配下の specs/ ディレクトリにおけるサブディレクトリ構成および運用ルールを specs/AGENTS.md に定義するためのガイドラインとMarkdownテンプレートです。 プロジェクト固有の構成を定義する場合は、docs/specs/AGENTS.md（または各コンポーネントの specs/AGENTS.md）を作成して適用します。

  • 機能仕様書（SPEC）および増分機能仕様書（incremental specification）の作成・編集にあたっては、specification-guide.md を参照し、定義されたセクション構成・フロントマター・記述ルールに従ってください。

  • 機能仕様書自体のフロントマターには実装進捗ステータスを持たせず、各コンポーネントの台帳（backlog/status.tsv および自動生成される backlog/spec.md）で一括管理します。

specs/AGENTS.md の記述規則

  1. 予約要素の定義:
    • specs/index.md（仕様総合台帳）、specs/index.link.tsv（仕様リンク台帳）、specs/id-seq-no.tsv（仕様採番管理台帳）、specs/AGENTS.md（本構成定義）、specs/incremental/（増分機能仕様ディレクトリ）は予約要素であり、他の目的で使用することはできません。
  2. ## Structure セクションの記述規則:
    • サブディレクトリ構成を定義する場合、必ず見出し ## Structure を作成し、以下の 3 列テーブルで記述します。
      • パス: specs/ 配下のディレクトリパスまたは予約ファイル名
      • 配置対象: 配置される仕様書の役割・機能範囲
      • 命名規則: 配置されるファイルの命名規則
  3. 仕様書の種別・配置と命名規則:
    • 機能仕様: specs/ 以下のサブディレクトリを含め、<SPEC-ID>.md（例: SPEC-001.md）とします。
    • 増分仕様: specs/incremental/ 直下に配置する <SPEC-I-ID>.md（例: SPEC-I-001.md）のみとします。
    • 共通仕様: ファイル名は SPEC-C-<name>.md（例: SPEC-C-error-handling.md）とします。incremental specification から参照され、他ソフトウェアコンポーネントからの参照も可能です。既定では specs/common/ や specs/model/ への配置を推奨とし、本ファイル（specs/AGENTS.md）の Structure 表で変更可能です。

specs/AGENTS.md テンプレート（Webアプリケーション / API標準）

以下は、コンポーネント配下に specs/AGENTS.md を作成する際の標準Markdownテンプレートです。

---
name: AGENTS.md
description: <コンポーネント名> 仕様書ディレクトリ構成および配置ルール
timestamp: YYYY-MM-DD
ai: ai-coauthored
---

# Specification Directory Rules: <コンポーネント名>

本コンポーネントにおける仕様書のサブディレクトリ構成および命名規則を以下に定義します。

## Structure

| パス | 配置対象 | 命名規則 |
| :--- | :--- | :--- |
| `auth/` | 認証・認可・セッション管理機能仕様 (Feature Spec) | `SPEC-001.md`, `SPEC-002.md` |
| `billing/` | 決済・請求・プラン管理機能仕様 (Feature Spec) | `SPEC-010.md`, `SPEC-011.md` |
| `user/` | ユーザー管理機能仕様 (Feature Spec) | `SPEC-020.md` |
| `common/` | 共通・非機能仕様（エラー規約、ヘッダー等） | `SPEC-C-<name>.md` (例: `SPEC-C-error-handling.md`) |
| `model/` | データモデル（DTO、エンティティ、スキーマ） | `SPEC-C-<name>.md` (例: `SPEC-C-auth-dto.md`) |
| `incremental/` | 増分機能仕様（自己完結型増分仕様）[予約] | `SPEC-I-001.md` 〜 |
| `index.md` | 仕様総合台帳（参照追跡）[予約] | `index.md` |
| `index.link.tsv` | 仕様リンク台帳（参照グラフ・リンク検証）[予約] | `index.link.tsv` |
| `id-seq-no.tsv` | 仕様ID採番管理台帳（KVTsv形式・最大連番・衝突防止）[予約] | `id-seq-no.tsv` |
| `AGENTS.md` | 仕様書ディレクトリ構成定義[予約] | `AGENTS.md` |

## 運用ルール

1.  **Feature Specification の配置**: 各ドメイン・機能分類に応じたサブディレクトリ配下に `SPEC-XXX.md` として作成します。
2.  **Incremental Specification の配置**: すべて `specs/incremental/` 直下に配置し、Feature Spec の台帳から相対パス（例: `../incremental/SPEC-I-001.md`）でマウントします。
3.  **新規作成時の採番管理**: 機能仕様（`<SPEC-ID>`）または増分仕様（`<SPEC-I-ID>`）を新規作成する際は、必ず `specs/id-seq-no.tsv`（KVTsv形式）を参照して採番し、値をインクリメント（+1）して保存します（アーカイブや削除時のID衝突防止）。`mise run aidev:kv-tsv`（`AIDEV-TOOL-28`）等のツールを利用して操作します。
4.  **台帳更新**: Incremental Spec や共通仕様の作成・更新時は、必ず `specs/index.md` および `specs/index.link.tsv` を同時に更新し、リンク検証を行います。

画面系コンポーネント（Webフロントエンド等）の ## Structure 例

## Structure

| パス | 配置対象 | 命名規則 |
| :--- | :--- | :--- |
| `screens/` | 画面UI機能仕様 (Feature Spec) | `SPEC-001.md`, `SPEC-002.md` |
| `components/` | 共通UIコンポーネント仕様 (Feature Spec) | `SPEC-010.md` |
| `common/` | 共通スタイル・共通UI規約 | `SPEC-C-<name>.md` |
| `model/` | UI状態・ViewModel・Form型定義 | `SPEC-C-<name>.md` |
| `incremental/` | 増分機能仕様（自己完結型増分仕様）[予約] | `SPEC-I-001.md` 〜 |
| `index.md` | 仕様総合台帳（参照追跡）[予約] | `index.md` |
| `index.link.tsv` | 仕様リンク台帳（参照グラフ・リンク検証）[予約] | `index.link.tsv` |
| `id-seq-no.tsv` | 仕様ID採番管理台帳（KVTsv形式・最大連番・衝突防止）[予約] | `id-seq-no.tsv` |
| `AGENTS.md` | 仕様書ディレクトリ構成定義[予約] | `AGENTS.md` |