2026.07.16 GitHub リファレンス v2.0

GitHub設計ハンドブック完全版

Markdown記法、GitHub拡張、Mermaid、README・Issue・PR、GitHub Spec Kit、AWS設計書、API・DB・運用設計、AI向け仕様書を、コピーして流用できる形式でまとめた実践リファレンスです。

Part	内容	主な収録項目	移動
1	Markdown完全リファレンス	見出し、リスト、表、画像、コード、引用、リンク、脚注、HTML	▶
2	GitHub Markdown拡張	Issue・PR参照、メンション、Alerts、数式、差分、折りたたみ	▶
3	Mermaid図表リファレンス	フロー、シーケンス、ER、状態遷移、ガント、Git Graph	▶
4	GitHubドキュメント運用	README、Issue、PR、ADR、ラベル、変更管理	▶
5	GitHub Spec Kit	Constitution、Specify、Plan、Tasks、実装・検証	▶
6	AWS設計書テンプレート	全体構成、ネットワーク、IAM、ECS、RDS、S3、監視、タグ	▶
7	システム設計テンプレート	要件、API、DB、画面、バッチ、運用、障害対応	▶
8	AI向け仕様書・Issue	Codex、Claude Code、Copilotへの実装・レビュー指示	▶
9	推奨ディレクトリ構成	docs、.github、specs、テンプレート配置例	▶
10	参考資料	GitHub公式、Spec Kit公式	▶

Part 1. Markdown完全リファレンス

1.1 見出し

書式

# 見出し1
## 見出し2
### 見出し3
#### 見出し4
##### 見出し5
###### 見出し6

表示例

見出し1

見出し2

見出し3

通常、1ファイル内の # 見出し1 は文書タイトルとして1つにします。

1.2 段落

書式

これは1つ目の段落です。

空行を入れると、次の段落になります。

表示例

これは1つ目の段落です。

空行を入れると、次の段落になります。

1.3 改行

Markdownでは、単なるソース上の改行が表示時に連結される場合があります。

方法1: 行末に半角スペースを2つ

1行目です。  
2行目です。

方法2: HTMLの改行タグ

1行目です。<br>
2行目です。

設計書では、基本的に空行で段落を分け、強制改行は必要な箇所だけに限定します。

1.4 太字・斜体・太字＋斜体・取り消し線

書式

**太字**

*斜体*

***太字＋斜体***

~~取り消し線~~

表示例

太字

斜体

太字＋斜体

~~取り消し線~~

1.5 インラインコード

ファイル名、コマンド、変数名、テーブル名などを文章中で強調します。

書式

本番環境では `.env` を配置せず、`AWS Secrets Manager` を使用します。

表示例

本番環境では .env を配置せず、AWS Secrets Manager を使用します。

バッククォート自体を表示する場合

`` `code` と記述します ``

1.6 エスケープ

Markdown記号をそのまま表示したい場合は、直前に \ を付けます。

書式

\# 見出しにしない
\* 斜体にしない
\- リストにしない

表示例

# 見出しにしない
* 斜体にしない
- リストにしない

1.7 水平線

書式

---

または

***

表示例

1.8 箇条書き

書式

- 項目1
- 項目2
- 項目3

表示例

項目1
項目2
項目3

入れ子

- AWS
  - Compute
    - ECS
    - Lambda
  - Storage
    - S3
    - EFS

表示例

AWS
Compute
- ECS
- Lambda
Storage
- S3
- EFS

1.9 番号付きリスト

書式

1. 要件を整理する
2. 仕様書を作成する
3. タスクに分割する
4. 実装する
5. 検証する

表示例

要件を整理する
仕様書を作成する
タスクに分割する
実装する
検証する

自動採番を使う書き方

ソース上をすべて 1. にすると、項目の途中追加が容易です。

1. 要件を整理する
1. 仕様書を作成する
1. 実装する

1.10 チェックリスト

書式

- [ ] 未着手
- [x] 完了
- [ ] レビュー待ち

表示例

未着手
完了
レビュー待ち

入れ子

- [ ] 認証機能
  - [x] Google OAuth
  - [ ] メールOTP
  - [ ] 権限確認

1.11 引用

書式

> これは引用文です。

表示例

これは引用文です。

複数行

> 仕様は実装より先に確定する。
>
> ただし、検証結果に応じて更新する。

入れ子

> 1段目
>> 2段目

1.12 コードブロック

言語指定なし

```
ここにコードや固定幅テキストを書く
```

Bash

```bash
docker compose up -d
docker compose logs -f
```

Python

```python
def hello(name: str) -> str:
    return f"Hello, {name}"
```

SQL

```sql
SELECT
    user_id,
    name
FROM m_user
WHERE company_id = :company_id;
```

JSON

```json
{
  "project": "CraftERP",
  "environment": "prod"
}
```

YAML

```yaml
name: CI

on:
  pull_request:
```

固定幅の構成図

```text
Internet
    │
CloudFront
    │
ALB
    │
ECS
    │
Aurora
```

1.13 コードブロック内にコードブロックを書く

外側を4個のバッククォートにします。

````md
```python
print("Hello")
```
````

1.14 表

基本書式

| 項目 | 内容 | 備考 |
|------|------|------|
| API | FastAPI | ECSで稼働 |
| DB | Aurora | PostgreSQL互換 |
| Storage | S3 | ファイル保存 |

表示例

項目	内容	備考
API	FastAPI	ECSで稼働
DB	Aurora	PostgreSQL互換
Storage	S3	ファイル保存

左寄せ・中央寄せ・右寄せ

| 左寄せ | 中央寄せ | 右寄せ |
|:-------|:--------:|-------:|
| A | B | 100 |
| C | D | 200 |

表内で改行する

| 項目 | 内容 |
|------|------|
| 対応環境 | Dev<br>Stg<br>Prod |

表内に `|` を書く

| 正規表現 | 説明 |
|----------|------|
| `A \| B` | AまたはB |

1.15 リンク

通常リンク

[表示名](https://example.com)

タイトル付き

[表示名](https://example.com "リンクの説明")

同一リポジトリ内の相対リンク

[ネットワーク設計](docs/architecture/network.md)

1階層上

[README](../README.md)

ファイル内の見出しへ移動

[API仕様へ移動](#api仕様)

明示的なアンカー

日本語・記号・同名見出しによるリンクの不安定さを避ける場合に使用します。

<a id="api-spec"></a>

## API仕様

[API仕様へ移動](#api-spec)

1.16 画像

基本書式

![代替テキスト](images/architecture.png)

タイトル付き

![AWS構成図](images/aws-architecture.png "AWS全体構成")

画像をリンクにする

[![画像の説明](images/banner.png)](https://example.com)

HTMLで幅を指定

<img src="images/architecture.png" alt="AWS構成図" width="800">

中央寄せ

<p align="center">
  <img src="images/architecture.png" alt="AWS構成図" width="800">
</p>

代替テキストには「画像」ではなく、画像の内容を簡潔に記述します。

1.17 相対パスの例

repository/
├── README.md
├── docs/
│   ├── architecture.md
│   └── images/
│       └── aws.png
└── src/

docs/architecture.md から docs/images/aws.png を表示する場合:

![AWS構成図](images/aws.png)

README.md から表示する場合:

![AWS構成図](docs/images/aws.png)

1.18 脚注

書式

AuroraはAWSのマネージドデータベースです。[^1]

[^1]: 詳細はAWS公式ドキュメントを参照してください。

複数行の脚注

本文です。[^note]

[^note]: 1行目の説明です。
    インデントした行は同じ脚注に含まれます。

1.19 HTMLコメント

Markdown上では表示されないメモです。

<!-- この内容は表示されません -->

複数行:

<!--
TODO:
- 構成図を更新する
- レビューを依頼する
-->

パスワード、APIキー、個人情報などは、コメントであってもGitHubへ保存しないでください。

1.20 折りたたみ

<details>
<summary>詳細を表示する</summary>

ここに詳細を書きます。

- 項目1
- 項目2

</details>

初期状態で開く

<details open>
<summary>詳細を表示する</summary>

最初から展開されます。

</details>

1.21 キーボード表現

<kbd>Ctrl</kbd> + <kbd>C</kbd>

表示例:

Ctrl + C

1.22 上付き・下付き

H<sub>2</sub>O

x<sup>2</sup>

表示例:

H₂O

x²

1.23 定義リスト風の表現

Markdown標準に定義リストはないため、太字または表を使います。

**RTO**  
障害発生後、サービスを復旧させるまでの目標時間。

**RPO**  
障害発生時に許容できるデータ損失時間。

1.24 目次テンプレート

縦長になりにくい表形式

## 目次

| No | セクション | リンク |
|---:|---|:---:|
| 1 | システム概要 | [▶](#system-overview) |
| 2 | ネットワーク | [▶](#network) |
| 3 | データベース | [▶](#database) |

対応する見出し

<a id="system-overview"></a>

# 1. システム概要

<a id="network"></a>

# 2. ネットワーク

<a id="database"></a>

# 3. データベース

目次へ戻るリンク

[↑ 目次へ戻る](#toc)

↑ 目次へ戻る

Part 2. GitHub Markdown拡張

2.1 Issue・Pull Requestへの参照

#123

別リポジトリ:

owner/repository#123

文章例:

Issue #123 の完了条件を満たしたため、PR #130 で対応します。

2.2 ユーザーやチームへのメンション

@username

チーム:

@organization/team-name

メンションは通知を発生させるため、必要な相手だけに使用します。

2.3 コミットへの参照

abcdef1

リポジトリを明示:

owner/repository@abcdef1

2.4 自動リンク

GitHub上ではURLや対応する参照が自動リンクされる場合があります。

https://github.com/

明示的な表示名を付けたい場合は通常リンクを使用します。

2.5 絵文字

:white_check_mark: 完了
:warning: 注意
:bulb: 提案
:rocket: リリース
:bug: 不具合
:lock: セキュリティ

表示例:

✅ 完了
⚠️ 注意
💡 提案
🚀 リリース

設計書では絵文字を多用せず、状態や注意の識別に限定すると読みやすくなります。

2.6 GitHub Alerts

NOTE

> [!NOTE]
> 補足情報です。

Note
補足情報です。

TIP

> [!TIP]
> 推奨する方法です。

Tip
推奨する方法です。

IMPORTANT

> [!IMPORTANT]
> 必ず理解しておくべき内容です。

Important
必ず理解しておくべき内容です。

WARNING

> [!WARNING]
> 設定を誤ると問題が発生する可能性があります。

Warning
設定を誤ると問題が発生する可能性があります。

CAUTION

> [!CAUTION]
> データ削除など、重大な影響がある操作です。

Caution
データ削除など、重大な影響がある操作です。

2.7 差分表示

```diff
- 削除した行
+ 追加した行
  変更していない行
```

表示例:

- DB_PASSWORDを.envに保存
+ DB_PASSWORDをSecrets Managerで管理

2.8 ファイル名を示すコードブロック

Markdown標準ではコードブロックにファイル名を表示する構文はありません。直前に明記します。

`backend/app/main.py`

```python
from fastapi import FastAPI
```

2.9 数式

インライン数式

式は $E = mc^2$ です。

ブロック数式

$$
RPO \leq 5\ \text{minutes}
$$

バッククォートを併用する形式

ドル記号との競合を避けたい場合:

$`E = mc^2`$

```math
E = mc^2
```

2.10 コード提案

Pull Requestレビューで使用する構文です。

```suggestion
return user_repository.find_by_id(user_id)
```

通常のMarkdownファイルではなく、PRの差分レビューコメントで使用します。

2.11 パーマリンクを使ったコード参照

変更される可能性があるブランチURLではなく、特定コミットの行範囲を参照すると、後から内容が変わりません。

文章例:

認証処理は、固定コミットの `auth.py` 20〜35行を参照してください。

2.12 タスクリストによる進捗管理

## 完了条件

- [x] APIを実装した
- [x] 単体テストを追加した
- [ ] 結合テストを実施した
- [ ] ドキュメントを更新した

「対応内容」と「完了条件」は分けます。実装項目を終えただけで、受入条件を満たしたとは限らないためです。

2.13 相対リンクを使ったドキュメント参照

- [システム全体構成](../architecture/system-overview.md)
- [ネットワーク設計](../architecture/network.md)
- [テーブル定義](../database/schema.md)

2.14 GitHubでの見出しリンクに関する注意

同じ見出しが複数ある場合や、日本語・記号を含む場合は、自動生成アンカーが分かりにくくなることがあります。

長期管理する文書では、明示的なIDを推奨します。

<a id="security-iam"></a>

## IAM設計

[IAM設計](#security-iam)

↑ 目次へ戻る

Part 3. Mermaid図表リファレンス

MermaidをGitHubで表示するには、コードブロックの言語識別子に mermaid を指定します。

3.1 フローチャート

基本

```mermaid
flowchart TD
    A[開始] --> B[仕様確認]
    B --> C[実装]
    C --> D[テスト]
    D --> E[完了]
```

flowchart TD
    A[開始] --> B[仕様確認]
    B --> C[実装]
    C --> D[テスト]
    D --> E[完了]

向き

記述	向き
`TD` / `TB`	上から下
`BT`	下から上
`LR`	左から右
`RL`	右から左

分岐

```mermaid
flowchart TD
    A[注文受付] --> B{在庫はあるか}
    B -- はい --> C[出荷指示]
    B -- いいえ --> D[欠品連絡]
```

サブグラフ

```mermaid
flowchart LR
    subgraph Public[Public Subnet]
        ALB[Application Load Balancer]
    end

    subgraph Private[Private Subnet]
        ECS[ECS Fargate]
        DB[(Aurora)]
    end

    ALB --> ECS
    ECS --> DB
```

3.2 シーケンス図

```mermaid
sequenceDiagram
    actor User as 利用者
    participant Front as Flutter
    participant API as FastAPI
    participant DB as Aurora

    User->>Front: ログイン情報を入力
    Front->>API: POST /login
    API->>DB: ユーザーを検索
    DB-->>API: ユーザー情報
    API-->>Front: アクセストークン
    Front-->>User: ログイン完了
```

条件分岐

```mermaid
sequenceDiagram
    participant API
    participant DB

    API->>DB: 在庫確認
    alt 在庫あり
        DB-->>API: 在庫数
    else 在庫なし
        DB-->>API: 0
    end
```

ループ

```mermaid
sequenceDiagram
    participant Batch
    participant S3

    loop 対象ファイルごと
        Batch->>S3: ファイル取得
        S3-->>Batch: ファイル
    end
```

3.3 ER図

```mermaid
erDiagram
    S_COMPANY ||--o{ M_USER : has
    S_COMPANY ||--o{ M_PARTNER : has
    M_AUTHORITY_GROUP ||--o{ M_USER : assigned

    S_COMPANY {
        UUID company_id PK
        VARCHAR code
        VARCHAR name
    }

    M_USER {
        UUID user_id PK
        UUID company_id FK
        UUID authority_group_id FK
        VARCHAR name
        VARCHAR email
    }
```

多重度の主な記号

記号	意味
`\|\|`	必ず1
`o\|`	0または1
`\|{`	1以上
`o{`	0以上

3.4 クラス図

```mermaid
classDiagram
    class UserService {
        +create_user()
        +find_user()
        +update_user()
    }

    class UserRepository {
        +save()
        +find_by_id()
    }

    UserService --> UserRepository
```

3.5 状態遷移図

```mermaid
stateDiagram-v2
    [*] --> Draft
    Draft --> Review : レビュー依頼
    Review --> Draft : 差戻し
    Review --> Approved : 承認
    Approved --> Implemented : 実装完了
    Implemented --> [*]
```

複合状態

```mermaid
stateDiagram-v2
    state Processing {
        [*] --> Validation
        Validation --> Saving
        Saving --> [*]
    }

    [*] --> Processing
    Processing --> Completed
```

3.6 ガントチャート

```mermaid
gantt
    title ユーザー管理機能
    dateFormat YYYY-MM-DD

    section 仕様
    要件整理       :done, spec1, 2026-07-01, 3d
    仕様レビュー   :done, spec2, after spec1, 2d

    section 実装
    API実装        :active, dev1, after spec2, 5d
    画面実装       :dev2, after spec2, 5d
    結合テスト     :test1, after dev1, 3d
```

3.7 円グラフ

```mermaid
pie showData
    title AWS月額費用の構成例
    "ECS" : 35
    "Aurora" : 40
    "S3" : 5
    "その他" : 20
```

3.8 Git Graph

```mermaid
gitGraph
    commit id: "initial"
    branch feature/user-management
    checkout feature/user-management
    commit id: "spec"
    commit id: "implementation"
    checkout main
    merge feature/user-management
```

3.9 ユーザージャーニー

```mermaid
journey
    title 発注登録
    section 入力
      発注先を選択: 5: User
      商品を検索: 4: User
      数量を入力: 4: User
    section 確認
      合計を確認: 5: User
      登録する: 5: User
```

3.10 タイムライン

```mermaid
timeline
    title Craft ERP 開発
    2026-07 : 基盤設計
            : ユーザー管理
    2026-08 : 商品管理
            : 取引先管理
    2026-09 : 発注・仕入
```

3.11 マインドマップ

```mermaid
mindmap
  root((Craft ERP))
    発注仕入
      発注
      入荷
      仕入計上
    受注出荷
      受注
      引当
      出荷
    在庫
      入出庫
      棚卸
```

3.12 Mermaidを使う際の実務上の注意

全体構成図が大きくなりすぎる場合は、draw.ioをマスターにする
Markdown内では、業務フロー・シーケンス・状態遷移など、変更頻度の高い図をMermaidで管理する
1つの図に情報を詰め込みすぎない
表示名と物理名を混在させる場合は、凡例を置く
AWS公式アイコンを多用する構成図はdraw.io、処理関係を示す図はMermaidが適している

↑ 目次へ戻る

Part 4. GitHubドキュメント運用

4.1 READMEテンプレート

# プロジェクト名

プロジェクトの目的を1〜3文で説明します。

## 概要

- 解決する課題:
- 対象ユーザー:
- 主な機能:

## 技術スタック

| 分類 | 技術 |
|------|------|
| Frontend | Flutter |
| Backend | FastAPI |
| Database | PostgreSQL |
| Infrastructure | AWS |
| CI/CD | GitHub Actions |

## システム構成

```mermaid
flowchart LR
    User --> Frontend
    Frontend --> API
    API --> DB
```

## ディレクトリ構成

```text
project/
├── frontend/
├── backend/
├── docs/
└── .github/
```

## 開発環境の起動

```bash
docker compose up -d
```

## テスト

```bash
pytest
flutter test
```

## ドキュメント

- [プロジェクト定義](docs/project-definition.md)
- [アーキテクチャ](docs/architecture/system-overview.md)
- [テーブル定義](docs/database/schema.md)

## ライセンス

ライセンスを記載します。

4.2 機能追加Issueテンプレート

## 概要

追加・変更する機能を簡潔に説明する。

## 背景

なぜこの対応が必要なのかを記載する。

## 目的

このIssueによって達成したい状態を記載する。

## 対象範囲

### 対象

- 対象機能1
- 対象機能2

### 対象外

- 今回は対応しない事項

## 仕様

### 業務ルール

- ルール1
- ルール2

### 処理概要

1. 入力を受け付ける
2. 入力値を検証する
3. DBへ登録する
4. 結果を返却する

### 入力

| 項目 | 必須 | 型 | 制約 |
|------|:---:|----|------|
| code | ○ | string | 20文字以内 |
| name | ○ | string | 200文字以内 |

### 出力

| 項目 | 型 | 説明 |
|------|----|------|
| id | UUID | 登録ID |
| created_at | datetime | 登録日時 |

## エラー処理

| 条件 | エラーコード | メッセージ |
|------|--------------|------------|
| コード重複 | DUPLICATE_CODE | すでに登録されています |

## セキュリティ

- 認証必須
- 企業IDによるデータ分離
- 権限グループを確認する

## テスト観点

- 正常系
- 必須項目未入力
- 境界値
- 重複登録
- 権限なし
- 他企業データへのアクセス

## ドキュメント更新

- [ ] API仕様
- [ ] テーブル定義
- [ ] 画面仕様
- [ ] 運用手順

## 完了条件

- [ ] 仕様どおりに実装されている
- [ ] テストが追加され、成功している
- [ ] 静的解析が成功している
- [ ] 関連ドキュメントが更新されている
- [ ] レビュー指摘が解消されている

## 対象ファイル候補

- `backend/app/...`
- `frontend/lib/...`
- `docs/...`

## 補足

追加情報があれば記載する。

4.3 不具合Issueテンプレート

## 概要

発生している不具合を簡潔に説明する。

## 発生環境

| 項目 | 値 |
|------|----|
| 環境 | Dev / Stg / Prod |
| ブラウザ | Chrome |
| OS | macOS |
| バージョン | v1.2.3 |

## 再現手順

1. 画面を開く
2. データを入力する
3. 登録ボタンを押す

## 実際の結果

現在発生している結果。

## 期待する結果

本来あるべき結果。

## ログ・エラー

```text
ここにエラー内容を貼る
```

## 原因調査

- 想定原因:
- 影響範囲:
- 関連Issue:

## 対応方針

修正方法を記載する。

## 回帰テスト

- [ ] 同じ条件で再発しない
- [ ] 関連機能に影響がない
- [ ] 他企業データに影響がない

## 完了条件

- [ ] 原因が説明されている
- [ ] 修正されている
- [ ] 回帰テストが追加されている
- [ ] 必要なドキュメントが更新されている

4.4 Pull Requestテンプレート

## 概要

このPRで行った変更を簡潔に説明する。

Closes #123

## 変更内容

- 変更1
- 変更2
- 変更3

## 変更理由

なぜこの実装方法を選んだのかを説明する。

## 動作確認

| 確認項目 | 結果 |
|----------|:---:|
| 正常系 | ✅ |
| 異常系 | ✅ |
| 権限確認 | ✅ |
| 他企業データ分離 | ✅ |

## テスト

```bash
pytest
flutter test
```

## スクリーンショット

画面変更がある場合に掲載する。

## 影響範囲

- API:
- DB:
- 画面:
- バッチ:
- 運用:

## ドキュメント

- [ ] API仕様を更新した
- [ ] DB定義を更新した
- [ ] 画面仕様を更新した
- [ ] 更新不要であることを確認した

## チェックリスト

- [ ] Issueの完了条件を満たしている
- [ ] 不要なデバッグコードがない
- [ ] シークレットが含まれていない
- [ ] テストが成功している
- [ ] 静的解析が成功している
- [ ] 破壊的変更を明記している

4.5 ADR（Architecture Decision Record）

ファイル例:

docs/adr/0001-use-aurora-postgresql.md

テンプレート:

# ADR-0001 Aurora PostgreSQLを採用する

- Status: Accepted
- Date: 2026-07-16
- Decision Owners: プロジェクト責任者

## Context

どのような背景・制約・課題があるか。

## Decision

採用する方針を明記する。

## Alternatives Considered

### RDS for PostgreSQL

- 長所:
- 短所:

### Aurora PostgreSQL

- 長所:
- 短所:

## Consequences

### Positive

- 良い影響

### Negative

- 受け入れる必要がある不利益

## Validation

判断が妥当だったかを確認する指標・時期。

## Related Documents

- [DB設計](../database/database-design.md)
- [AWS構成](../architecture/aws-overview.md)

4.6 変更履歴

## 変更履歴

| バージョン | 日付 | 変更内容 | 変更者 |
|------------|------|----------|--------|
| 1.0 | 2026-07-01 | 初版作成 | Author |
| 1.1 | 2026-07-16 | 認証構成を更新 | Author |

Gitで履歴が残る場合でも、公開資料や正式設計書では重要変更を表で残すと理解しやすくなります。

4.7 レビュー記録

## レビュー記録

| 日付 | レビュアー | 指摘 | 対応 | 状態 |
|------|------------|------|------|------|
| 2026-07-16 | Reviewer | 権限確認が不足 | 仕様へ追記 | 完了 |

4.8 文書の状態

- Status: Draft

候補:

状態	意味
Draft	作成中
In Review	レビュー中
Approved	承認済み
Implemented	実装済み
Deprecated	廃止予定
Archived	保管済み

↑ 目次へ戻る

Part 5. GitHub Spec Kit

Spec Kitのコマンドや生成物はバージョン更新で変わる可能性があります。実際の導入時は公式リポジトリの最新版を確認してください。

5.1 基本的な流れ

flowchart LR
    A[Constitution] --> B[Specify]
    B --> C[Clarify]
    C --> D[Plan]
    D --> E[Tasks]
    E --> F[Implement]
    F --> G[Validate]

工程	目的
Constitution	プロジェクトの非交渉原則を定義
Specify	何を、なぜ作るかを定義
Clarify	曖昧点を解消
Plan	技術構成・実装方針を定義
Tasks	実行可能なタスクへ分割
Implement	タスクに従って実装
Validate	仕様・完了条件に照らして検証

5.2 Constitutionテンプレート

# Project Constitution

## 1. Single Source of Truth

正式な仕様は `docs/` および承認済みの `specs/` に置く。

## 2. Human-Designed, AI-Assisted

要件、業務ルール、基本設計、受入判断は人が行う。
詳細設計、実装、テストではAIを活用する。

## 3. Cross-Feature Consistency

機能単体ではなく、発注・仕入・在庫・買掛などのデータおよび処理の整合性を維持する。

## 4. Tenant Isolation

すべての業務データで `company_id` による企業分離を保証する。

## 5. Documentation First

仕様変更は、実装より先に正本ドキュメントへ反映する。

## 6. Testability

完了条件は検証可能な内容で記載する。

## 7. Security

シークレットをソースコードやGitへ保存しない。
最小権限を適用する。

5.3 Specifyへの入力テンプレート

# 機能名

## 背景

なぜ必要か。

## 目的

どの状態を実現するか。

## 利用者

誰が使うか。

## ユーザーストーリー

- 利用者として、○○したい。なぜなら△△だから。
- 管理者として、○○を確認したい。

## 業務ルール

- ルール1
- ルール2

## 対象範囲

### 対象

- 対象事項

### 対象外

- 対象外事項

## 受入条件

- Given:
- When:
- Then:

## 不明点

- 確認が必要な事項

コマンド入力の例:

/speckit.specify docs/_inbox/user-management.md の内容を基に、
ユーザー管理機能の仕様を作成してください。
技術選定や実装方法ではなく、利用者、業務ルール、機能要件、
受入条件を明確にしてください。

5.4 Planへの入力テンプレート

/speckit.plan

以下の前提で技術計画を作成してください。

- Frontend: Flutter Web
- Backend: FastAPI
- Database: PostgreSQL
- ORM: SQLAlchemy
- Infrastructure: AWS ECS Fargate
- Authentication: Google OAuth
- Tenant isolation: company_id
- Testing: flutter test / pytest
- Documentation: docs/ を正本とする

既存のアーキテクチャおよび命名規約を優先し、
新しいライブラリやテーブルの追加は必要性を説明してください。

5.5 Tasksへの入力テンプレート

/speckit.tasks

計画を、依存関係が分かる実行可能なタスクに分割してください。

各タスクに以下を含めてください。

- 目的
- 対象ファイル
- 変更内容
- 依存タスク
- テスト方法
- 完了条件

並行実行可能なタスクには [P] を付けてください。
ドキュメント更新とテスト追加を独立したタスクとして含めてください。

5.6 仕様レビュー用チェックリスト

## 仕様レビュー

### 業務

- [ ] 利用者が明確
- [ ] 業務目的が明確
- [ ] 対象・対象外が明確
- [ ] 業務ルールが明確
- [ ] 例外条件が明確

### データ

- [ ] 登録・更新・削除の条件が明確
- [ ] 他機能への影響が整理されている
- [ ] 企業間データ分離が考慮されている
- [ ] 監査項目が考慮されている

### 検証

- [ ] 受入条件が検証可能
- [ ] 正常系・異常系がある
- [ ] 境界値が定義されている
- [ ] 完了条件が明確

5.7 仕様変更時の原則

Issue
  ↓
正本仕様の更新
  ↓
Planの更新
  ↓
Tasksの更新
  ↓
実装変更
  ↓
テスト・受入

spec.md、plan.md、tasks.md の内容が矛盾したまま進めないようにします。上位の仕様変更を下位成果物へ反映してから実装します。

↑ 目次へ戻る

Part 6. AWS設計書テンプレート

6.1 AWS全体構成書の目次

# AWSシステム構成設計書

## 目次

| No | セクション | リンク |
|---:|---|:---:|
| 1 | システム概要 | [▶](#aws-overview) |
| 2 | 全体構成 | [▶](#aws-architecture) |
| 3 | ネットワーク | [▶](#aws-network) |
| 4 | コンピューティング | [▶](#aws-compute) |
| 5 | データベース | [▶](#aws-database) |
| 6 | ストレージ | [▶](#aws-storage) |
| 7 | 認証・権限 | [▶](#aws-iam) |
| 8 | シークレット | [▶](#aws-secrets) |
| 9 | 監視・ログ | [▶](#aws-monitoring) |
| 10 | バックアップ | [▶](#aws-backup) |
| 11 | タグ | [▶](#aws-tags) |
| 12 | 障害対応 | [▶](#aws-dr) |

6.2 システム概要

<a id="aws-overview"></a>

## 1. システム概要

### 目的

本システムが解決する業務課題を記載する。

### 対象環境

| 環境 | 用途 | AWSアカウント | リージョン |
|------|------|---------------|------------|
| Dev | 開発 | XXXXX | ap-northeast-1 |
| Stg | 検証 | XXXXX | ap-northeast-1 |
| Prod | 本番 | XXXXX | ap-northeast-1 |

### 利用者

| 利用者 | 利用方法 |
|--------|----------|
| 一般利用者 | Webブラウザ |
| 管理者 | 管理画面 |
| 運用担当 | AWS Console |

6.3 全体構成

<a id="aws-architecture"></a>

## 2. 全体構成

```text
Internet
   │
Route 53
   │
CloudFront
   │
AWS WAF
   │
ALB
   │
ECS Fargate
   ├── Aurora PostgreSQL
   ├── S3
   ├── Secrets Manager
   └── CloudWatch Logs
```

### 構成方針

- アプリケーションはECS Fargateで実行する
- ECSタスクはステートレスにする
- 業務データはAuroraへ保存する
- ファイルはS3へ保存する
- シークレットはSecrets Managerで管理する
- ログはCloudWatch Logsへ送信する

6.4 ネットワーク設計

<a id="aws-network"></a>

## 3. ネットワーク

### VPC

| 項目 | 値 |
|------|----|
| VPC CIDR | 10.0.0.0/16 |
| Region | ap-northeast-1 |
| Availability Zones | 2以上 |

### Subnet

| 名前 | CIDR | AZ | 種別 | 主な配置 |
|------|------|----|------|----------|
| public-a | 10.0.1.0/24 | ap-northeast-1a | Public | ALB |
| public-c | 10.0.2.0/24 | ap-northeast-1c | Public | ALB |
| private-app-a | 10.0.11.0/24 | ap-northeast-1a | Private | ECS |
| private-app-c | 10.0.12.0/24 | ap-northeast-1c | Private | ECS |
| private-db-a | 10.0.21.0/24 | ap-northeast-1a | Private | Aurora |
| private-db-c | 10.0.22.0/24 | ap-northeast-1c | Private | Aurora |

### Route Table

| Subnet種別 | 宛先 | ターゲット |
|------------|------|------------|
| Public | 10.0.0.0/16 | local |
| Public | 0.0.0.0/0 | Internet Gateway |
| Private App | 10.0.0.0/16 | local |
| Private App | 0.0.0.0/0 | NAT Gateway |
| Private DB | 10.0.0.0/16 | local |

### Security Group

| SG | Inbound | Source |
|----|---------|--------|
| alb-sg | TCP 443 | 0.0.0.0/0 |
| ecs-sg | App Port | alb-sg |
| db-sg | TCP 5432 | ecs-sg |

> [!WARNING]
> DBのポートを `0.0.0.0/0` に公開しない。

6.5 ECS設計

<a id="aws-compute"></a>

## 4. ECS Fargate

### Cluster

| 項目 | 値 |
|------|----|
| Cluster name | craft-erp-prod |
| Launch type | Fargate |
| Region | ap-northeast-1 |

### Service

| 項目 | 値 |
|------|----|
| Desired count | 2 |
| Deployment type | Rolling update |
| Health check | `/health` |
| Public IP | Disabled |

### Task Definition

| 項目 | 値 |
|------|----|
| CPU | 要件に応じて設定 |
| Memory | 要件に応じて設定 |
| Container port | 8000 |
| Log driver | awslogs |
| Task role | アプリがAWSサービスへ接続する権限 |
| Execution role | ECR取得・ログ出力・シークレット注入 |

### 永続化方針

- コンテナ内へ業務ファイルを永続保存しない
- 一時ファイルは `/tmp` を使用し、処理後に削除する
- ファイルはS3へ保存する
- ログは標準出力・標準エラーへ出力する
- セッションをコンテナ内へ保持しない

6.6 Lambda設計

## Lambda

| 項目 | 値 |
|------|----|
| Function name | example-function |
| Runtime | 要件に応じて設定 |
| Memory | 要件に応じて設定 |
| Timeout | 要件に応じて設定 |
| Trigger | EventBridge / S3 / API Gateway |
| IAM Role | 最小権限 |
| Logs | CloudWatch Logs |

### 用途

- イベント駆動処理
- 短時間のバッチ
- S3アップロード後の処理
- スケジュール処理

### 非採用条件

- 長時間処理
- OSへ継続的な設定が必要
- 常駐プロセス
- 大容量ローカルディスクへ依存

6.7 Aurora・RDS設計

<a id="aws-database"></a>

## 5. データベース

### 基本情報

| 項目 | 値 |
|------|----|
| Engine | Aurora PostgreSQL |
| Writer | 1 |
| Reader | 1以上 |
| Multi-AZ | 有効 |
| Encryption | KMS |
| Public access | 無効 |
| Backup retention | 要件に応じて設定 |
| Deletion protection | 本番は有効 |

### 接続

| 接続元 | 接続先 | Port | 制御 |
|--------|--------|------|------|
| ECS | Aurora | 5432 | Security Group |
| 運用端末 | Aurora | 直接接続しない | 踏み台・SSM・VPN等を検討 |

### 可用性

- ストレージ冗長化
- ReaderからWriterへのフェールオーバー構成
- アプリはクラスタエンドポイントへ接続
- 接続切断時のリトライ方針をアプリ側に実装

### データ保護

- 自動バックアップ
- ポイントインタイムリカバリ
- 手動スナップショット
- 誤削除と障害対策を別々に設計

6.8 S3設計

<a id="aws-storage"></a>

## 6. S3

### Bucket

| 項目 | 値 |
|------|----|
| Bucket name | 命名規則に従う |
| Public access block | 有効 |
| Versioning | 要件に応じて有効 |
| Encryption | SSE-KMS または SSE-S3 |
| Lifecycle | 要件に応じて設定 |

### オブジェクト構成

```text
s3://bucket/
├── company/{company_id}/
│   ├── product-images/
│   ├── documents/
│   └── exports/
└── system/
    ├── templates/
    └── batch/
```

### アクセス方式

- アプリはIAM Roleで接続する
- ユーザーのアップロード・ダウンロードは署名付きURLを使用する
- S3アクセスキーをソースコードや `.env` に保存しない

6.9 IAM設計

<a id="aws-iam"></a>

## 7. IAM

### Role一覧

| Role | 割当先 | 主な権限 |
|------|--------|----------|
| ecs-task-execution-role | ECS Agent | ECR、Logs、Secrets取得 |
| ecs-task-role | アプリ | S3、必要なAWS API |
| lambda-role | Lambda | 対象サービスのみ |
| github-actions-role | GitHub Actions | ECR Push、ECS Deploy |

### 原則

- 最小権限
- 人とアプリの権限を分離
- 長期アクセスキーを避ける
- リソース単位で絞り込む
- 本番変更権限を限定する

6.10 Secrets Manager設計

<a id="aws-secrets"></a>

## 8. Secrets Manager

### 管理対象

| Secret | 内容 |
|--------|------|
| database/credentials | DBユーザー・パスワード |
| oauth/google | OAuthクライアントシークレット |
| external-api/example | 外部APIキー |

### 非シークレット

以下はParameter Storeまたは通常の環境変数を検討する。

- ログレベル
- リージョン
- 機能フラグ
- 公開URL

### 運用

- シークレットをGitへ保存しない
- ローテーション方針を定義する
- 誰が参照できるかをIAMで制御する
- CloudTrailで操作を監査する

6.11 監視・ログ設計

<a id="aws-monitoring"></a>

## 9. 監視・ログ

### 監視項目

| 対象 | 指標 | アラーム例 |
|------|------|------------|
| ALB | 5XX | 一定数以上 |
| ECS | CPU | 80%以上 |
| ECS | Memory | 80%以上 |
| ECS | Running tasks | Desired未満 |
| Aurora | CPU | 80%以上 |
| Aurora | Connections | 上限に接近 |
| Aurora | Freeable memory | 閾値未満 |
| S3 | 4XX / 5XX | 異常増加 |

### ログ

| ログ | 保存先 |
|------|--------|
| アプリログ | CloudWatch Logs |
| ALBアクセスログ | S3 |
| CloudTrail | S3 / CloudWatch |
| WAFログ | CloudWatch Logs / S3 |

### アプリログの推奨項目

- timestamp
- level
- request_id
- company_id
- user_id
- endpoint
- status_code
- duration_ms
- error_code

> [!CAUTION]
> パスワード、アクセストークン、医療情報、カード情報などをログへ出力しない。

6.12 バックアップ設計

<a id="aws-backup"></a>

## 10. バックアップ

| 対象 | 方法 | 保持期間 | 復旧確認 |
|------|------|----------|----------|
| Aurora | 自動バックアップ | 要件に応じる | 定期復元テスト |
| Aurora | 手動スナップショット | リリース前等 | 必要時 |
| S3 | Versioning | 要件に応じる | 削除復旧テスト |
| 設定 | IaC / Git | 履歴保持 | 再構築テスト |

### RTO・RPO

| 対象 | RTO | RPO |
|------|-----|-----|
| API | 例: 1時間 | 例: 5分 |
| DB | 例: 2時間 | 例: 5分 |
| ファイル | 例: 4時間 | 例: 1時間 |

6.13 AWSタグ標準

<a id="aws-tags"></a>

## 11. AWSタグ

| Key | 必須 | 値の例 | 用途 |
|-----|:---:|--------|------|
| Project | ○ | CraftERP | プロジェクト識別 |
| Environment | ○ | dev / stg / prod | 環境識別 |
| Component | ○ | api / db / storage | 構成分類 |
| Owner | ○ | team-name | 管理責任 |
| ManagedBy | ○ | Terraform / CDK / Manual | 管理方法 |
| CostCenter | 任意 | personal-dev | コスト配賦 |
| DataClassification | 任意 | public / internal / confidential | データ分類 |
| Backup | 任意 | daily / none | バックアップ方針 |

6.14 障害対応

<a id="aws-dr"></a>

## 12. 障害対応

### 障害レベル

| Level | 定義 | 例 |
|-------|------|----|
| P1 | 全面停止・重大漏洩 | API全停止 |
| P2 | 主要機能停止 | 受注登録不可 |
| P3 | 一部機能異常 | CSV出力不可 |
| P4 | 軽微 | 表示崩れ |

### 初動

1. 影響範囲を確認
2. 直近変更を確認
3. CloudWatch Logsを確認
4. メトリクスを確認
5. 必要ならロールバック
6. 利用者へ連絡
7. 原因と再発防止を記録

### 記録

| 項目 | 内容 |
|------|------|
| 発生日時 | |
| 検知方法 | |
| 影響範囲 | |
| 暫定対応 | |
| 根本原因 | |
| 恒久対応 | |
| 再発防止 | |

↑ 目次へ戻る

Part 7. システム設計テンプレート

7.1 要件定義

# 機能要件定義書

## 1. 背景

## 2. 目的

## 3. 利用者

## 4. 現行業務

## 5. 対象業務

## 6. 機能要件

| ID | 要件 | 優先度 | 受入条件 |
|----|------|--------|----------|
| FR-001 | ユーザーを登録できる | Must | 正常に登録される |

## 7. 非機能要件

| ID | 分類 | 要件 |
|----|------|------|
| NFR-001 | 性能 | 95%のAPIを2秒以内 |
| NFR-002 | 可用性 | 月間稼働率目標を定義 |
| NFR-003 | セキュリティ | 企業間データを分離 |

## 8. 対象外

## 9. 制約

## 10. 用語

7.2 API仕様

# ユーザー登録API

## Endpoint

`POST /api/v1/users`

## Authentication

Bearer Token必須

## Authorization

`USER_CREATE` 権限が必要

## Request Headers

| Header | 必須 | 値 |
|--------|:---:|----|
| Authorization | ○ | Bearer token |
| Content-Type | ○ | application/json |

## Request Body

```json
{
  "code": "U0001",
  "name": "ユーザー名",
  "email": "user@example.com"
}
```

| 項目 | 必須 | 型 | 最大長 | 説明 |
|------|:---:|----|-------:|------|
| code | ○ | string | 20 | ユーザーコード |
| name | ○ | string | 200 | 氏名 |
| email | ○ | string | 255 | メールアドレス |

## Response 201

```json
{
  "user_id": "uuid",
  "code": "U0001",
  "name": "ユーザー名"
}
```

## Errors

| HTTP | Error Code | 条件 |
|-----:|------------|------|
| 400 | VALIDATION_ERROR | 入力不正 |
| 401 | UNAUTHORIZED | 未認証 |
| 403 | FORBIDDEN | 権限なし |
| 409 | DUPLICATE_CODE | コード重複 |
| 500 | INTERNAL_ERROR | システムエラー |

## Processing

1. 認証情報を検証
2. 企業IDを取得
3. 権限を確認
4. 入力値を検証
5. 重複を確認
6. DBへ登録
7. 監査ログを記録
8. 結果を返す

## Test Cases

- 正常登録
- コード重複
- メール形式不正
- 権限なし
- 他企業コードとの同名登録

7.3 テーブル定義

# m_user

## 概要

システムを利用するユーザーを管理する。

## カラム

| No | 論理名 | 物理名 | 型 | NULL | PK | FK | Default | 説明 |
|---:|--------|--------|----|:---:|:---:|:---:|---------|------|
| 1 | ユーザーID | user_id | UUID | × | ○ | | | 主キー |
| 2 | 企業ID | company_id | UUID | × | | ○ | | 所属企業 |
| 3 | コード | code | VARCHAR(20) | × | | | | 企業内一意 |
| 4 | 氏名 | name | VARCHAR(200) | × | | | | |
| 5 | メール | email | VARCHAR(255) | ○ | | | | |
| 6 | 作成日時 | created_at | TIMESTAMPTZ | × | | | now() | |
| 7 | 更新日時 | updated_at | TIMESTAMPTZ | × | | | now() | |

## 制約

| 制約名 | 種別 | 対象 |
|--------|------|------|
| pk_m_user | PRIMARY KEY | user_id |
| uq_m_user_company_code | UNIQUE | company_id, code |
| fk_m_user_company | FOREIGN KEY | company_id |

## Index

| Index | カラム | 用途 |
|-------|--------|------|
| idx_m_user_company | company_id | 企業別検索 |
| idx_m_user_email | email | メール検索 |

## 業務ルール

- コードは企業内で一意
- 物理削除せず、状態管理を検討
- 他企業のユーザーを参照できない

7.4 画面仕様

# ユーザー一覧画面

## 画面概要

ユーザーを検索・一覧表示し、登録・編集画面へ遷移する。

## 利用権限

- USER_VIEW
- USER_CREATE
- USER_EDIT

## 検索条件

| 項目 | UI | 必須 | 説明 |
|------|----|:---:|------|
| コード | TextField | | 部分一致 |
| 氏名 | TextField | | 部分一致 |
| 状態 | Select | | 有効・無効 |

## 一覧項目

| 項目 | ソート | 説明 |
|------|:---:|------|
| コード | ○ | |
| 氏名 | ○ | |
| メール | ○ | |
| 状態 | ○ | |

## 操作

| 操作 | 条件 | 結果 |
|------|------|------|
| 検索 | 条件入力後 | 一覧更新 |
| 新規登録 | 権限あり | 登録画面へ |
| 編集 | 権限あり | 編集画面へ |

## エラー表示

| 条件 | 表示 |
|------|------|
| 検索失敗 | 画面上部にエラー |
| 0件 | 該当データなし |
| 権限なし | 操作ボタン非表示または無効 |

7.5 バッチ仕様

# 在庫集計バッチ

## 目的

日次で在庫残高を集計する。

## 実行方式

| 項目 | 値 |
|------|----|
| スケジュール | 毎日 02:00 |
| タイムゾーン | Asia/Tokyo |
| 起動元 | EventBridge |
| 実行先 | ECS Task / Lambda |

## 入力

- 対象日
- 企業ID（任意）

## 処理

1. 対象企業を取得
2. 前日残高を取得
3. 当日の入出庫を集計
4. 当日残高を計算
5. 集計テーブルへ登録
6. 実行結果を記録

## 冪等性

- 同一対象日・企業の再実行で二重登録しない
- 既存データを安全に再計算できる

## エラー時

- 企業単位で失敗を記録
- 全体停止条件を定義
- 再実行方法を記載

7.6 運用手順書

# 運用手順書

## 1. 目的

## 2. 対象環境

## 3. 必要権限

## 4. 通常運用

### デプロイ

1. PRをマージ
2. GitHub Actionsを確認
3. ECSデプロイを確認
4. ヘルスチェックを確認
5. 主要機能を確認

### ログ確認

1. AWS Consoleを開く
2. CloudWatch Logsを開く
3. 対象Log Groupを選択
4. request_idで検索する

## 5. 障害対応

## 6. ロールバック

## 7. バックアップ復旧

## 8. 緊急連絡先

7.7 テスト仕様

# テスト仕様

## テスト対象

## 前提条件

## テストケース

| ID | 分類 | 条件 | 操作 | 期待結果 |
|----|------|------|------|----------|
| TC-001 | 正常 | 必須項目入力 | 登録 | 登録成功 |
| TC-002 | 異常 | コード重複 | 登録 | 重複エラー |
| TC-003 | 権限 | 権限なし | 登録 | 403 |
| TC-004 | 分離 | 他企業ID指定 | 参照 | 取得不可 |

## 実施結果

| ID | 結果 | Evidence | 備考 |
|----|:---:|----------|------|
| TC-001 | Pass | ログ・画像 | |

↑ 目次へ戻る

Part 8. AI向け仕様書・Issue

8.1 AIへの基本指示

## 作業方針

- Issueと正本ドキュメントを優先する
- 不明点を勝手に仕様化しない
- 既存アーキテクチャと命名規約を尊重する
- 機能間・テーブル間の整合性を確認する
- 企業間データ分離を維持する
- シークレットをコードへ埋め込まない
- 必要なテストとドキュメント更新を含める
- Issueの対象外へ変更を広げない

8.2 Codexへの実装指示テンプレート

## 依頼

Issueの仕様に基づいて実装してください。

## 優先する情報源

1. このIssue
2. `docs/` の正本仕様
3. 対象機能の `spec.md`
4. `plan.md`
5. `tasks.md`
6. 既存コード

矛盾がある場合は、上位の情報源を優先し、勝手に解釈せず明記してください。

## 実装要件

- 既存の設計・命名規約に従う
- 必要最小限の変更に限定する
- 企業間データ分離を維持する
- エラーコードと利用者向けメッセージを実装する
- 単体テストを追加する
- 関連ドキュメントを更新する

## 禁止事項

- Issueにない機能追加
- 無関係なリファクタリング
- 新規依存ライブラリの無断追加
- `.env` やコードへのシークレット追加
- テストを通すためだけの仕様変更

## 完了時の報告

- 変更概要
- 変更ファイル
- テスト結果
- 静的解析結果
- 未解決事項
- 仕様との差異

8.3 Claude Codeへのレビュー指示テンプレート

## レビュー目的

実装がIssue・仕様書・設計方針に適合しているか確認してください。

## レビュー観点

### 仕様適合

- 受入条件を満たしているか
- 対象外の変更が含まれていないか
- 業務ルールが欠落していないか

### 整合性

- テーブル間の整合性
- 機能間のデータ連携
- 発注・仕入・在庫・買掛など関連処理への影響
- company_idによる企業分離

### セキュリティ

- 認証・認可
- 入力検証
- シークレット管理
- ログへの機密情報出力
- SQLインジェクション等

### 品質

- 例外処理
- エラーメッセージ
- テスト不足
- 不要な複雑性
- 既存規約との不整合

## 出力形式

### Critical

重大な問題。マージ不可。

### Major

仕様・品質上の重要な問題。

### Minor

改善推奨。

各指摘に以下を含めてください。

- 対象ファイル・行
- 問題
- 影響
- 修正案
- 根拠となる仕様

8.4 GitHub Copilot coding agent向けIssue

## Goal

このIssueで実現する最終状態を1〜3文で記載する。

## Context

- 関連仕様:
- 関連機能:
- 技術スタック:
- 制約:

## Requirements

1. 要件1
2. 要件2
3. 要件3

## Files likely involved

- `backend/...`
- `frontend/...`
- `docs/...`

## Acceptance criteria

- [ ] 条件1
- [ ] 条件2
- [ ] 条件3

## Tests

- [ ] 単体テスト
- [ ] 結合テスト
- [ ] 権限テスト
- [ ] テナント分離テスト

## Do not

- 無関係な変更を行わない
- 仕様にないテーブルを追加しない
- シークレットをコミットしない

8.5 AIに調査だけを依頼するテンプレート

## 依頼

実装は行わず、現状調査と対応案の提示だけを行ってください。

## 調査対象

- 対象機能
- 関連ファイル
- 関連テーブル
- 関連API
- 関連テスト

## 確認事項

1. 現在の処理フロー
2. 仕様との差異
3. 影響範囲
4. 想定リスク
5. 対応案
6. 推奨案と理由

## 禁止事項

- ファイル変更
- コード生成
- マイグレーション実行
- 依存関係変更

8.6 AIが迷いにくい仕様の書き方

悪い例:

ユーザー管理をいい感じに作る。

改善例:

企業管理者が、自社に所属するシステム利用者を登録・編集・無効化できるようにする。

- ユーザーは必ず1つの企業に所属する
- ユーザーコードは企業内で一意とする
- 削除は物理削除ではなく無効化とする
- 他企業のユーザーは参照・変更できない
- 登録、編集、無効化には個別の権限を必要とする

明記すべき要素

要素	内容
Who	誰が使うか
Why	なぜ必要か
What	何を実現するか
Rules	業務ルール
Input	入力
Output	出力
Error	エラー
Scope	対象・対象外
Acceptance	完了判定
Impact	他機能への影響

↑ 目次へ戻る

Part 9. 推奨ディレクトリ構成

9.1 プロジェクト全体

project/
├── .github/
│   ├── ISSUE_TEMPLATE/
│   │   ├── feature.md
│   │   ├── bug.md
│   │   └── config.yml
│   ├── PULL_REQUEST_TEMPLATE.md
│   └── workflows/
├── docs/
│   ├── _inbox/
│   ├── adr/
│   ├── architecture/
│   ├── database/
│   ├── api/
│   ├── screen/
│   ├── operations/
│   ├── security/
│   ├── research/
│   ├── glossary.md
│   └── notes.md
├── specs/
│   └── 001-feature-name/
│       ├── spec.md
│       ├── plan.md
│       ├── tasks.md
│       └── checklists/
├── backend/
├── frontend/
├── tests/
├── AGENTS.md
├── CLAUDE.md
└── README.md

9.2 docs内の役割

ディレクトリ	役割
`_inbox/`	未整理の仕様メモ・依頼元資料
`adr/`	重要な技術判断
`architecture/`	システム・AWS・ネットワーク構成
`database/`	テーブル・データ設計
`api/`	API仕様
`screen/`	画面仕様
`operations/`	運用・障害・バックアップ
`security/`	セキュリティ方針・権限設計
`research/`	技術比較・調査記録

9.3 文書の正本ルール

## 正本

- 業務・機能仕様: `specs/` または `docs/`
- アーキテクチャ: `docs/architecture/`
- テーブル定義: `docs/database/`
- API仕様: `docs/api/`
- 運用手順: `docs/operations/`
- 一時メモ: `docs/_inbox/`
- 実装タスク: GitHub Issues

同じ仕様を複数ファイルへ重複記載せず、参照リンクを使います。

↑ 目次へ戻る

参考資料

GitHub公式

GitHub Spec Kit公式

github/spec-kit

最終チェックリスト

文書を公開・登録する前に確認します。

タイトルが内容を表している
目次リンクが動作する
見出し階層が飛んでいない
コードブロックの開始・終了が一致している
相対リンクが正しい
画像の代替テキストがある
シークレットや個人情報が含まれていない
仕様の対象・対象外が明確
完了条件が検証可能
関連文書へのリンクがある
表が横に広がりすぎていない
同じ情報を複数箇所へ重複記載していない

↑ 目次へ戻る

本ページは Markdown 正本（research/github-design-handbook/reports/github-design-handbook-complete-v2.md）から生成しています。 GitHub、Spec Kit、AWS、AIツールの仕様は変更されるため、実務へ適用する際は各公式情報も確認してください。

収録内容

Markdown、GitHub拡張、Mermaidの記法と表示例
README、Issue、Pull Request、ADR、GitHub Spec Kitの実務テンプレート
AWS、API、DB、運用設計、AI向け実装・レビュー指示の雛形

Related Service

設計と運用の共通言語を整え、生成AIを含む開発作業の再現性を高めるための実践資料です。

Research 一覧クラシス（小売向け業務アプリ）

目次

Part 1. Markdown完全リファレンス

1.1 見出し

書式

表示例

見出し1

見出し2

見出し3

1.2 段落

書式

表示例

1.3 改行

方法1: 行末に半角スペースを2つ

方法2: HTMLの改行タグ

1.4 太字・斜体・太字＋斜体・取り消し線

書式

表示例

1.5 インラインコード

書式

表示例

バッククォート自体を表示する場合

1.6 エスケープ

書式

表示例

1.7 水平線

書式

表示例

1.8 箇条書き

書式

表示例

入れ子

表示例

1.9 番号付きリスト

書式

表示例

自動採番を使う書き方

1.10 チェックリスト

書式

表示例

入れ子

1.11 引用

書式

表示例

複数行

入れ子

1.12 コードブロック

言語指定なし

Bash

Python

SQL

JSON

YAML

固定幅の構成図

1.13 コードブロック内にコードブロックを書く

1.14 表

基本書式

表示例

左寄せ・中央寄せ・右寄せ

表内で改行する

表内に | を書く

1.15 リンク

通常リンク

タイトル付き

同一リポジトリ内の相対リンク

1階層上

ファイル内の見出しへ移動

明示的なアンカー

1.16 画像

基本書式

タイトル付き

画像をリンクにする

HTMLで幅を指定

中央寄せ

1.17 相対パスの例

1.18 脚注

書式

複数行の脚注

1.19 HTMLコメント

1.20 折りたたみ

初期状態で開く

表内に `|` を書く