用語集

本フローで使う用語定義。

初見は 10語 だけ。くわしくは各章へ。

やること

初見10語を読む
不明語だけ各章へ

完了: Plan / Rules / Phase を説明できる

本フロー正式な記録で使う用語定義。製品 changelog・スタック詳細はメモを優先。

初見向け — 10語だけ

初日はこの10語だけ押さえれば十分。くわしくは下の各節へ。

用語	一言
Plan	実装前のタスク分解・完了条件（Cursor は Plan モード）
ADR	設計の「なぜ」を1段落で残す記録
Phase	開発の段階（1=規約, 2=Plan, 3=設計, 4–7=実装〜PR）
Rules	AI が毎回読むプロジェクト指示（`.cursor/rules/` 等）
PRD	要件定義書。関係者合意用
Draft PR	レビュー用の下書き PR。早めに出す
`.cursor/rules/`	Cursor 専用ルール置き場
`tasks/todo.md`	Plan の共有正本（チェックリスト）
エージェント	AI に自律的に調査・編集させるモード
Won't	今回やらないこと（スコープ固定に必須）

Cursor / Claude Code / Codex / AIツール関連

`.cursor/rules/`

Cursor がプロジェクト固有の AI 指示を読むディレクトリ。配下の .mdc が個別ルール。

`.mdc` ファイル

Cursor ルールの拡張子。[frontmatter](#frontmatter) 付き Markdown。

`frontmatter`

ファイル先頭の YAML メタデータ。Cursor では description / alwaysApply / globs を指定。

例:

---
description: コーディング規約
alwaysApply: true
---

# 本文ここから

`alwaysApply`

[frontmatter](#frontmatter) のブール値。true なら毎ターンコンテキストに載る。

true: 常に適用。ドメイン制約など必須事項向け
省略 / false: [globs](#globs) 合致時または @rule-name 時のみ
注意: 多用するとコスト・性能に効く。本当に必須だけ true に

`globs`

ルールを適用するファイルパターン。合致ファイル編集時だけコンテキストに含まれる。

globs: **/*.py → Python 編集時のみ
globs: tests/** → tests 配下編集時のみ

`AGENTS.md`

AI エージェント向け指示書。Codex は作業ディレクトリに近い AGENTS.md を優先（Phase 1 Codex）。

`CLAUDE.md`

Claude Code がセッション開始時に読むファイル。リポジトリ直下は全体方針、サブディレクトリはローカル規約（セットアップ 12 項）。

`.claude/skills/`

Claude Code の反復手順置き場。長い運用は Skill に分離し CLAUDE.md は短く保つ。

`Hooks`（Claude Code）

特定イベント後にコマンドを強制実行。lint や危険コマンド検査向け。

`.agents/skills/`（Codex）

Codex の共有 Skill 置き場。各 Skill は SKILL.md（name / description）と任意の scripts/。

`.codex/config.toml`（Codex）

Codex のプロジェクト上書き設定。trusted プロジェクトのみ読み込む。

開発手法 / TDD

TDD (Test-Driven Development)

テストを実装より先に書く。Red-Green-Refactor を高速に回す。

Red-Green-Refactor

TDD の基本サイクル。

RED: 失敗するテストを書く（実装はまだ書かない）
GREEN: テストが通る最小コード（汚くてもよい）
REFACTOR: テストを通したまま設計改善（新規テスト追加禁止）

Inside-out TDD / Outside-in TDD

TDD の 2 アプローチ。

Inside-out: ドメインから外側へ。モック最小。本ドキュメントの推奨
Outside-in: UI/API から内側へ。依存をモックで埋める

AAA (Arrange-Act-Assert)

テストを 3 段階で書く構造。Arrange（準備）→ Act（1 回実行）→ Assert（検証）。

C0 / C1 / C2 カバレッジ

テストでコードが実行された割合の種類。

C0: 全行が 1 回以上実行されたか
C1: if/else の両分岐が実行されたか
C2: 複合条件の各項が真偽両方を取ったか

目安: C0 80%+ / C1 70%+。

設計概念

詳細はメモ — 開発手法。AI 協働フロー本体とは別レイヤ。

レイヤ構成 (Interface / Application / Domain / Infrastructure)

DDD でよく使う 4 層。Domain は他レイヤに依存しない。

Interface: REST / GraphQL / CLI 等
Application: ユースケース運用
Domain: 業務ロジック・エンティティ・値オブジェクト
Infrastructure: DB・外部 API 等

依存逆転 / 依存性逆転原則 (DIP)

抽象 (Protocol / Interface) に依存させ、Domain が Infrastructure に依存しないようにする。

Pure function

副作用なし。同じ入力 → 同じ出力。テスト・並列実行しやすい。

値オブジェクト (Value Object)

アイデンティティを持たない不変オブジェクト。Python では @dataclass(frozen=True) が多い。

業務例外 / 技術例外

業務ルール違反（WARNING）とインフラ起因（ERROR）を分離する方針。

Protocol / Interface

抽象化の呼び名違い。Python は typing.Protocol、Java/TS は implements。

品質・運用

冪等性 (Idempotency)

同じ操作を何度実行しても結果が変わらない性質。リトライ対策に必須。

楽観ロック / 悲観ロック

並行更新の制御。楽観はバージョン番号、悲観は行ロック。

N+1問題

一覧取得後に N 回クエリが走る ORM の性能問題。joinedload 等で対策。

認証 (AuthN) / 認可 (AuthZ)

AuthN = 「誰か」。AuthZ = 「やっていいか」。混同はセキュリティ事故の原因。

テスト・インフラ

testcontainers

テスト時に Docker で本物の DB 等を起動するライブラリ（testcontainers.com）。

モック / スタブ / フィクスチャ

Mock = 呼び出し検証可能。Stub = 固定戻り値。Fixture = 前提条件の整備。

構造化ログ (Structured Logging)

JSON 等の機械可読形式でログ出力。検索・集約しやすい。

OpenTelemetry

分散トレース・メトリクス・ログのオープン標準（opentelemetry.io）。

下書き PR（下書き PR（Draft PR））

レビュー前の PR。早期に CI を回し、完成後 Ready for review に。

機能フラグ (Feature Flag)

本番で機能 ON/OFF を動的切替。段階リリース・緊急 OFF に使う。

マイグレーション (forward / rollback)

forward = 変更適用。rollback = 巻き戻し。両方向を staging で確認してから本番。

CI green

CI の全チェック（ビルド・テスト・lint 等）が成功している状態。

ドキュメント

ADR / Architecture Decision Records

「なぜそうしたか」を時系列で残す形式。docs/adr/NNNN-<slug>.md。詳細は 11.7 ADR。

`docs/` と個人メモ (`z_docs/`)

docs/: チーム公式。レビュー必須
z_docs/: 任意の作業メモ。公式成果物には含めない

Mermaid

テキストで図を書く記法。本サイトでは最小構文を推奨（HTML ラベル禁止）。

操作・運用

強制確認ルール (操作確認)

対象: git add/commit/push/merge/rebase、docker exec、rm、mv（重要）、aws 等。

実行前に [操作確認] コマンド: XXX を実行します。許可をお願いします。 と出力し、許可を待つ。

.codex/config.toml（Codex）

`.codex/config.toml`（Codex）