phasegate 0.110.0 → 0.112.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/LICENSE +20 -215
- package/README.ja.md +306 -663
- package/README.md +115 -2
- package/docs/folder_management_rules.md +237 -172
- package/docs/guide/cli-reference.md +10 -0
- package/package.json +2 -2
package/README.ja.md
CHANGED
|
@@ -1,779 +1,406 @@
|
|
|
1
1
|
# Phasegate
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
[](https://opensource.org/licenses/MIT)
|
|
4
|
+
[](https://nodejs.org/)
|
|
4
5
|
|
|
5
|
-
AI
|
|
6
|
+
**AI が書いたコードに「設計してから書け」を物理的に強制するツールキット。**
|
|
7
|
+
Claude Code / Codex / Cursor / Copilot — どの AI agent でも同じ防御が効きます。
|
|
6
8
|
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
## 目次
|
|
10
|
-
|
|
11
|
-
- [何ができるのか](#何ができるのか)
|
|
12
|
-
- [クイックスタート](#クイックスタート)
|
|
13
|
-
- [5層防御モデル](#5層防御モデル)
|
|
14
|
-
- [設定 (phasegate.config.json)](#設定-phasegateconfigjson)
|
|
15
|
-
- [CLIコマンド](#cliコマンド)
|
|
16
|
-
- [AIDLC スキル](#aidlc-スキル)
|
|
17
|
-
- [メタデータ規約](#メタデータ規約)
|
|
18
|
-
- [Claude Code Hooks](#claude-code-hooks)
|
|
19
|
-
- [Codex CLI Integration](#codex-cli-integration)
|
|
20
|
-
- [カスタムフェーズゲート](#カスタムフェーズゲート)
|
|
21
|
-
- [CI/CD テンプレート](#cicd-テンプレート)
|
|
22
|
-
- [導入後のプロジェクト構造](#導入後のプロジェクト構造)
|
|
9
|
+
[English README](README.md) ・ [開発者ガイド](DEVELOPMENT.ja.md)
|
|
23
10
|
|
|
24
11
|
---
|
|
25
12
|
|
|
26
|
-
##
|
|
13
|
+
## 30 秒でわかる Phasegate
|
|
27
14
|
|
|
28
|
-
|
|
15
|
+
1. **AI agent が設計文書なしで実装ファイルを書こうとすると、Write/Edit/Bash がブロックされる**（PreToolUse hook）
|
|
16
|
+
2. **コミット前に L1〜L3 のバリデーションが自動で走り**、レイヤー違反・テスト品質違反・依存方向違反を弾く
|
|
17
|
+
3. **ブロック時のエラーは AI が読んで自己修正できる形式**（理由・必要な設計文書・次に打つべきスキル名が出る）
|
|
29
18
|
|
|
30
|
-
|
|
31
|
-
|---|---|
|
|
32
|
-
| **フェーズゲート** | 設計文書が存在しないとソースコードの書き込みをブロック。カスタムゲートも定義可能 |
|
|
33
|
-
| **5層バリデーション** | L1(AST) → L2(Pre-commit) → L3(CI) → L4(週次) の段階的品質チェック |
|
|
34
|
-
| **28 AIDLC スキル** | 要求定義 → 設計 → テスト設計 → TDD実装の全フェーズをスキルとして提供 |
|
|
35
|
-
| **Claude Code Hooks** | Write/Edit 時に自動でゲートチェック・Biome lint を実行 |
|
|
36
|
-
| **Codex CLI Hooks** | Bash 書き込み時にフェーズゲート / 保護ファイル / Biome lint を実行（ネイティブ `apply_patch` は pre-commit でカバー） |
|
|
37
|
-
| **Quick Mode** | バグ修正・ドキュメント修正など軽微な変更ではゲートを緩和して高速実行 |
|
|
19
|
+
`npx phasegate init` を 1 回打てば、上記が全部入ります。
|
|
38
20
|
|
|
39
21
|
---
|
|
40
22
|
|
|
41
|
-
##
|
|
23
|
+
## なぜ Phasegate か
|
|
42
24
|
|
|
43
|
-
|
|
25
|
+
AI agent は速いが、設計を飛ばして実装に走ります。レイヤー境界を平気で越え、`any` 型で型システムを骨抜きにし、テストはあるけど実装の写経になっている — そんなコードを高速に量産します。レビューで全部捕まえるのは現実的ではありません。
|
|
44
26
|
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
### 1. インストール
|
|
27
|
+
Phasegate はこれを **「人がレビューで防ぐ」のではなく「ツールがファイルシステム/git/CI レベルで防ぐ」** で解決します。設計文書がなければそもそも書けない。レイヤー違反があれば commit が通らない。AI agent 自身が「次にどの設計スキルを呼べばいいか」を読んで自走します。
|
|
48
28
|
|
|
49
|
-
|
|
50
|
-
npm install --save-dev phasegate
|
|
51
|
-
```
|
|
52
|
-
|
|
53
|
-
### 2. プロジェクト初期化
|
|
54
|
-
|
|
55
|
-
```bash
|
|
56
|
-
npx phasegate init --name <プロジェクト名> --preset standard
|
|
57
|
-
```
|
|
29
|
+
### こんなプロジェクトで効きます
|
|
58
30
|
|
|
59
|
-
|
|
31
|
+
| 向いている | 向いていない |
|
|
32
|
+
|---|---|
|
|
33
|
+
| AI agent に複数機能を任せる中〜大規模開発 | 数百行の使い捨てスクリプト |
|
|
34
|
+
| Clean Architecture / DDD / Hexagonal を採用 | 構造を持たないアドホック実装 |
|
|
35
|
+
| TDD・テスト規約を守らせたい | テストを書かない方針 |
|
|
36
|
+
| 設計とコードの乖離を継続的に検出したい | コードのみが Source of Truth |
|
|
60
37
|
|
|
61
|
-
|
|
38
|
+
---
|
|
62
39
|
|
|
63
|
-
|
|
40
|
+
## 動いている様子
|
|
64
41
|
|
|
65
|
-
|
|
42
|
+
AI agent が設計なしに `src/order/order-service.ts` を書こうとすると、PreToolUse hook が止めます。
|
|
66
43
|
|
|
67
|
-
```bash
|
|
68
|
-
claude # プロジェクトルートで起動
|
|
69
44
|
```
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
npx phasegate update-skills # スキルを最新版に同期
|
|
45
|
+
フェーズゲート違反: src/order/order-service.ts
|
|
46
|
+
対象スコープ: Level 3 (実装), Unit: order
|
|
47
|
+
ブロック理由:
|
|
48
|
+
- docs/product/construction/order/domain_model.md が存在しません
|
|
49
|
+
- docs/product/construction/order/logical_design.md が存在しません
|
|
50
|
+
次のアクション: /story-implementor スキルを使用して設計フェーズから開始してください。
|
|
51
|
+
実行例: /story-implementor --unit order
|
|
78
52
|
```
|
|
79
53
|
|
|
80
|
-
|
|
54
|
+
Claude Code / Codex はこのメッセージを読んで `/story-implementor` を起動し、ドメイン設計→論理設計→TDD 実装の順で進みます。人間が「設計やってからね」と言わなくても自走します。
|
|
81
55
|
|
|
82
|
-
|
|
56
|
+
---
|
|
83
57
|
|
|
84
|
-
|
|
85
|
-
|---|---|---|---|
|
|
86
|
-
| **L0** | AI agent runtime (Claude Code / Codex) + Husky git hooks | PreToolUse が Write/Edit/Bash をゲート違反時に block（reflection 未済 / 保護ファイル / Bash 迂回検知）、PostToolUse が自動 lint/format、Stop で ReentryGuard + `complete-check`、`.husky/pre-commit` が staged files に L2 validators を適用、`.husky/commit-msg` が `Work-Item: WI-XXX` trailer を強制 | runtime 自動起動（`.claude/settings.json` / `.codex/hooks.json` / `.husky/` 経由） |
|
|
87
|
-
| **L1** | エディタ保存時 | import グラフ・レイヤー違反・`@unit`/`@layer` メタデータ・AI アンチパターン | `npx phasegate lint` |
|
|
88
|
-
| **L2** | コミット前（pre-commit hook 内でも評価） | フェーズゲート・メタデータ完全性・`@work-item-id` 反映（L2-STORY-REFLECTION）・テスト品質 | `npx phasegate validate --layer L2` |
|
|
89
|
-
| **L3** | CI/CD | セキュリティ・パフォーマンス・カバレッジ・要件トレーサビリティ (※) | `npx phasegate validate --layer L3` |
|
|
90
|
-
| **L4** | 週次（CI cron、現状 `layers.L4.enabled: false` がデフォルト — プロジェクト側で opt-in） | 設計-コード乖離検出・文書間整合性・デッドコード検出・文書鮮度・ポインタ検証 | `npx phasegate validate --layer L4` |
|
|
58
|
+
## クイックスタート
|
|
91
59
|
|
|
92
|
-
|
|
60
|
+
### 前提
|
|
93
61
|
|
|
94
|
-
|
|
62
|
+
Node.js >= 18, npm >= 9, TypeScript 5.x
|
|
95
63
|
|
|
96
|
-
|
|
64
|
+
### 3 ステップ
|
|
97
65
|
|
|
98
|
-
|
|
99
|
-
|
|
100
|
-
|
|
101
|
-
| `agent` | AI エージェント連携 | キー値テキスト（`OVERALL: PASS`, `VALIDATOR: L2-001`） |
|
|
102
|
-
| `ci` | CI/CD パイプライン | 構造化 JSON（GitHub Actions 等で解析可能） |
|
|
66
|
+
```bash
|
|
67
|
+
# 1. インストール
|
|
68
|
+
npm install --save-dev phasegate
|
|
103
69
|
|
|
104
|
-
|
|
70
|
+
# 2. プロジェクトを初期化
|
|
71
|
+
npx phasegate init --name my-project --with-husky
|
|
105
72
|
|
|
106
|
-
|
|
73
|
+
# 3. AI agent を起動して /product-architect から始める
|
|
74
|
+
claude
|
|
75
|
+
> /product-architect
|
|
76
|
+
```
|
|
107
77
|
|
|
108
|
-
|
|
109
|
-
|---|---|---|
|
|
110
|
-
| **日本語テスト名** | L2-003 | `it()` / `test()` のテスト名が日本語であること |
|
|
111
|
-
| **`actual` 変数** | L2-003 | `expect()` の対象を `const actual` に代入していること |
|
|
112
|
-
| **CLI E2E テスト存在** | L2-013 | CLI コマンドに対応する E2E テストが存在すること |
|
|
78
|
+
`init` が生成するもの:
|
|
113
79
|
|
|
114
|
-
|
|
115
|
-
|
|
116
|
-
|
|
117
|
-
|
|
118
|
-
|
|
119
|
-
|
|
120
|
-
|
|
121
|
-
|
|
122
|
-
|
|
123
|
-
// Assert
|
|
124
|
-
expect(actual).toEqual(expectedResult);
|
|
125
|
-
});
|
|
126
|
-
|
|
127
|
-
// FAIL — 英語テスト名 + actual 変数なし
|
|
128
|
-
it('should return user', async () => {
|
|
129
|
-
const result = await sut.findByUserId(userId);
|
|
130
|
-
expect(result).toEqual(expectedResult);
|
|
131
|
-
});
|
|
132
|
-
```
|
|
80
|
+
- `phasegate.config.json` — 品質設定の Single Source of Truth
|
|
81
|
+
- `skills/` — 28 の AIDLC スキル一式
|
|
82
|
+
- `.claude/skills/` ・ `.codex/skills/` — agent 向けの skill symlink
|
|
83
|
+
- `.claude/settings.json` — PreToolUse / PostToolUse / Stop hook
|
|
84
|
+
- `.codex/hooks.json` — Codex CLI hooks 設定（`--agent codex|both` 時）
|
|
85
|
+
- `docs/principles/*.md` — アーキテクチャ哲学・テスト規約（immutable）
|
|
86
|
+
- `docs/folder_management_rules.md` — ドキュメント配置ルール（**正本**）
|
|
87
|
+
- `--with-husky` を付けると `.husky/pre-commit` ・ `.husky/commit-msg` も配置
|
|
133
88
|
|
|
134
|
-
|
|
89
|
+
**`init` が生成しないもの**（後で skill が作る）:
|
|
135
90
|
|
|
136
|
-
|
|
91
|
+
- `docs/inception/` 配下の WI directory — `/product-architect` 以降のスキル実行で生成
|
|
92
|
+
- `docs/product/` 配下の確定設計文書 — `/domain-designer` `/logical-designer` 等が生成
|
|
93
|
+
- `docs/ADR/` — `/skill-creator` や手動で必要に応じて作成
|
|
137
94
|
|
|
138
|
-
|
|
95
|
+
「設計してから書け」を強制する仕組みなので、設計文書はユーザーがスキル経由で作るのが既定動作です。
|
|
139
96
|
|
|
140
|
-
|
|
97
|
+
### Codex CLI を使う場合
|
|
141
98
|
|
|
142
|
-
```
|
|
143
|
-
|
|
144
|
-
|
|
145
|
-
"stories": [
|
|
146
|
-
{
|
|
147
|
-
"storyId": "H07-01",
|
|
148
|
-
"storyMappings": [
|
|
149
|
-
{
|
|
150
|
-
"acId": "AC-1",
|
|
151
|
-
"testReferences": [
|
|
152
|
-
{
|
|
153
|
-
"filePath": "src/__tests__/unit/feature.test.ts",
|
|
154
|
-
"testType": "unit",
|
|
155
|
-
"testName": "特定のシナリオをテストする"
|
|
156
|
-
}
|
|
157
|
-
]
|
|
158
|
-
},
|
|
159
|
-
{
|
|
160
|
-
"acId": "AC-2",
|
|
161
|
-
"testReferences": []
|
|
162
|
-
}
|
|
163
|
-
]
|
|
164
|
-
}
|
|
165
|
-
]
|
|
166
|
-
}
|
|
99
|
+
```bash
|
|
100
|
+
npx phasegate init --name my-project --agent codex --with-husky
|
|
101
|
+
codex features enable codex_hooks # Codex 本体の feature flag を手動で有効化
|
|
167
102
|
```
|
|
168
103
|
|
|
169
|
-
|
|
104
|
+
両方使う場合は `--agent both`。詳細は [Codex Integration Guide](docs/guide/codex-integration.md) を参照。
|
|
170
105
|
|
|
171
|
-
###
|
|
172
|
-
|
|
173
|
-
L4 は CI の cron スケジュールで週次実行します。`consistency-check` テンプレートを使います:
|
|
106
|
+
### アップデート
|
|
174
107
|
|
|
175
108
|
```bash
|
|
176
|
-
|
|
177
|
-
npx phasegate
|
|
109
|
+
npm update phasegate
|
|
110
|
+
npx phasegate update-skills # スキルを最新版に再デプロイ
|
|
178
111
|
```
|
|
179
112
|
|
|
180
|
-
|
|
113
|
+
---
|
|
181
114
|
|
|
182
|
-
|
|
115
|
+
## 主な機能
|
|
183
116
|
|
|
184
|
-
|
|
117
|
+
| 機能 | できること |
|
|
118
|
+
|---|---|
|
|
119
|
+
| **フェーズゲート** | 設計文書がないと実装ファイルへの Write/Edit/Bash をブロック。AIDLC 準拠 / カスタム gate の両方をサポート |
|
|
120
|
+
| **5 層バリデーション (L0-L4)** | エディタ保存 → pre-commit → CI → 週次まで段階的に品質チェック |
|
|
121
|
+
| **28 AIDLC スキル** | 要求定義 → ドメイン設計 → テスト設計 → TDD 実装をスキルとして提供 |
|
|
122
|
+
| **Quick Mode** | バグ修正・docs・テスト追加など軽微変更ではゲートを緩和して高速化 |
|
|
123
|
+
| **Claude Code / Codex Hooks** | Write/Edit/Bash 時に自動でゲートチェック・lint を実行 |
|
|
124
|
+
| **HarnessError 形式** | 全エラーに ADR 参照 + 修正例が含まれ、AI が自己修正できる |
|
|
125
|
+
| **Baseline (retrofit)** | 既存リポジトリ導入時、`baseline` snapshot に登録した既存ファイルは構造的に編集されるまで gate 対象外 |
|
|
185
126
|
|
|
186
127
|
---
|
|
187
128
|
|
|
188
|
-
##
|
|
189
|
-
|
|
190
|
-
プロジェクトルートに配置する品質設定の Single Source of Truth です。
|
|
129
|
+
## 5 層防御モデル
|
|
191
130
|
|
|
192
|
-
```
|
|
193
|
-
|
|
194
|
-
|
|
195
|
-
|
|
196
|
-
|
|
197
|
-
|
|
198
|
-
|
|
199
|
-
|
|
200
|
-
|
|
201
|
-
|
|
202
|
-
|
|
203
|
-
|
|
204
|
-
|
|
205
|
-
|
|
206
|
-
|
|
207
|
-
|
|
208
|
-
|
|
209
|
-
|
|
210
|
-
}
|
|
211
|
-
},
|
|
212
|
-
"phaseDependencies": {
|
|
213
|
-
"preset": "standard",
|
|
214
|
-
"storyReflection": { "enabled": true }
|
|
215
|
-
},
|
|
216
|
-
"protectedFiles": {
|
|
217
|
-
"exclude": ["package.json"]
|
|
218
|
-
},
|
|
219
|
-
"baseline": {
|
|
220
|
-
"enabled": true,
|
|
221
|
-
"path": ".phasegate/baseline.json"
|
|
222
|
-
}
|
|
223
|
-
}
|
|
131
|
+
```
|
|
132
|
+
+------------------------------------------------------------------+
|
|
133
|
+
| L0 AI agent runtime + git hooks |
|
|
134
|
+
| PreToolUse / PostToolUse / Stop / SessionStart / |
|
|
135
|
+
| UserPromptSubmit + .husky/pre-commit + .husky/commit-msg |
|
|
136
|
+
+------------------------------------------------------------------+
|
|
137
|
+
| L1 エディタ時 / `phasegate lint` |
|
|
138
|
+
| @unit / @layer メタデータ, レイヤー違反, AI アンチパターン |
|
|
139
|
+
+------------------------------------------------------------------+
|
|
140
|
+
| L2 pre-commit |
|
|
141
|
+
| phase-gate, story-reflection, テスト品質 (AAA/日本語名) |
|
|
142
|
+
+------------------------------------------------------------------+
|
|
143
|
+
| L3 CI/CD |
|
|
144
|
+
| security, performance, coverage 90%/95%, 要件カバレッジ |
|
|
145
|
+
+------------------------------------------------------------------+
|
|
146
|
+
| L4 週次 (default off) |
|
|
147
|
+
| 設計-コード乖離, 文書整合性, デッドコード, 文書鮮度 |
|
|
148
|
+
+------------------------------------------------------------------+
|
|
224
149
|
```
|
|
225
150
|
|
|
226
|
-
|
|
151
|
+
| Layer | 実行タイミング | コマンド |
|
|
152
|
+
|---|---|---|
|
|
153
|
+
| **L0** | AI agent / git hook | runtime 自動（`.claude/settings.json` 等） |
|
|
154
|
+
| **L1** | 保存時 | `npx phasegate lint` |
|
|
155
|
+
| **L2** | コミット前 | `npx phasegate validate --layer L2` |
|
|
156
|
+
| **L3** | CI/CD | `npx phasegate validate --layer L3` |
|
|
157
|
+
| **L4** | 週次 cron | `npx phasegate validate --layer L4` |
|
|
227
158
|
|
|
228
|
-
`
|
|
159
|
+
エラーは `HarnessError` 形式（理由 / ADR 参照 / 修正例）で返されるため、AI agent が自己修正できます。
|
|
229
160
|
|
|
230
|
-
|
|
161
|
+
> `--layer L0` の `L0-001` / `L0-002` は legacy validator で `enabled: false`。実体の L0 は agent-integration の hook と Husky です。
|
|
231
162
|
|
|
232
|
-
|
|
233
|
-
|---|---|---|---|
|
|
234
|
-
| **minimal** | L1, L2 | -- | プロトタイプ・学習 |
|
|
235
|
-
| **standard** | L1-L3 | 90% | 通常開発（デフォルト） |
|
|
236
|
-
| **strict** | L1-L4 | 95% | 本番・エンタープライズ |
|
|
163
|
+
詳細: [5-Layer Defense Model](docs/guide/layer-model.md)
|
|
237
164
|
|
|
238
|
-
|
|
165
|
+
---
|
|
239
166
|
|
|
240
|
-
|
|
167
|
+
## 28 AIDLC スキル
|
|
241
168
|
|
|
242
|
-
|
|
243
|
-
{
|
|
244
|
-
"layers": {
|
|
245
|
-
"L1": {
|
|
246
|
-
"enabled": true,
|
|
247
|
-
"rules": {
|
|
248
|
-
"no-any-abuse": "warning",
|
|
249
|
-
"no-comment-flood": "off"
|
|
250
|
-
}
|
|
251
|
-
}
|
|
252
|
-
}
|
|
253
|
-
}
|
|
254
|
-
```
|
|
169
|
+
AIDLC (AI-Driven Development Life Cycle) は **要求定義 → 設計 → テスト設計 → TDD 実装** の順序を強制するプロセスです。各スキルは前のレベルの成果物を入力にします。
|
|
255
170
|
|
|
256
|
-
|
|
257
|
-
|---|---|---|
|
|
258
|
-
| `require-unit-comment` | L1-001 | `@unit` アノテーションの存在 |
|
|
259
|
-
| `require-layer-comment` | L1-002 | `@layer` アノテーションの存在 |
|
|
260
|
-
| `no-layer-violation` | L1-003 | import グラフ解析・レイヤー依存方向違反の検出 |
|
|
261
|
-
| `enforce-folder-structure` | L1-004 | フォルダ構造と宣言レイヤーの一致 |
|
|
262
|
-
| `no-any-abuse` | L1-005 | `any` 型の濫用検出 |
|
|
263
|
-
| `no-code-duplication` | L1-006 | コード重複の検出 |
|
|
264
|
-
| `no-ghost-file` | L1-007 | 未参照ファイルの検出 |
|
|
265
|
-
| `no-comment-flood` | L1-008 | 過剰コメントの検出 |
|
|
266
|
-
| `it-test-mock-detection` | L1-017 | テストでの不適切なモック使用を検出 |
|
|
267
|
-
| `stub-comment-detection` | L1-018 | スタブコメント（TODO/FIXME/HACK 等）の検出 |
|
|
268
|
-
|
|
269
|
-
### phaseDependencies.preset -- フェーズゲート構成
|
|
270
|
-
|
|
271
|
-
`project.preset` とは独立して設定します。
|
|
272
|
-
|
|
273
|
-
| プリセット | ゲート | storyReflection | 用途 |
|
|
274
|
-
|---|---|---|---|
|
|
275
|
-
| **full** | 全 AIDLC ゲート | `logical_design` + `domain_model` required | AIDLC フルセレモニー |
|
|
276
|
-
| **standard** | コアゲート | `logical_design` required | 通常開発 |
|
|
277
|
-
| **minimal** | なし | 無効 | プロトタイプ |
|
|
278
|
-
| **custom** | `gates[]` で定義 | `storyReflection.mappings` で定義 | 完全カスタマイズ（`override: true` 必須） |
|
|
171
|
+
**最初の一歩**: Claude Code / Codex 内で `/product-architect` を実行。
|
|
279
172
|
|
|
280
|
-
###
|
|
173
|
+
### 5 グループ（28 スキル）
|
|
281
174
|
|
|
282
|
-
|
|
175
|
+
| グループ | スキル |
|
|
176
|
+
|---|---|
|
|
177
|
+
| **Foundation (4)** | `/product-architect` `/story-writer` `/story-mapper` `/unit-designer` |
|
|
178
|
+
| **Design (5)** | `/domain-designer` `/logical-designer` `/mock-designer` `/uiux-designer` `/environment-designer` |
|
|
179
|
+
| **Test Engineering (7)** | `/unit-test-designer` `/it-test-designer` `/scenario-test-designer` `/unit-test-logic-designer` `/it-test-logic-designer` `/scenario-test-logic-designer` `/test-coverage-checker` |
|
|
180
|
+
| **Implementation (4)** | `/story-implementor` `/quick-implementor` `/implementation-planner` `/implementation-readiness-checker` |
|
|
181
|
+
| **Verification (8)** | `/consistency-checker` `/cascade-updater` `/codex-delegator` `/codebase-mapper` `/doc-freshness-checker` `/pointer-validator` `/engineering-perspective` `/skill-creator` |
|
|
182
|
+
|
|
183
|
+
各スキルの詳細・成果物・前提条件: [Skills Overview](docs/guide/skills-overview.md)
|
|
283
184
|
|
|
284
|
-
|
|
185
|
+
---
|
|
285
186
|
|
|
286
|
-
|
|
187
|
+
## メタデータ規約
|
|
287
188
|
|
|
288
|
-
|
|
289
|
-
2. 検出した各 US について、inception 側のファイルが存在するかチェック
|
|
290
|
-
3. 存在する場合、対応する product 側のファイルに `@story-id` アノテーションが含まれるかチェック
|
|
291
|
-
4. **含まれていなければ書き込みをブロック**
|
|
189
|
+
ソースファイル先頭に `@unit` / `@layer` を、テストには `@story` または `@work-item-id` を記載します。L1 / L2 はこれを使ってレイヤー違反検出・drift-detection・WI トレーサビリティを行います。
|
|
292
190
|
|
|
293
|
-
```
|
|
294
|
-
|
|
295
|
-
|
|
296
|
-
|
|
191
|
+
```typescript
|
|
192
|
+
// @unit config-foundation
|
|
193
|
+
// @layer domain
|
|
194
|
+
// @work-item-id WI-042 ← 任意（traceability に貢献）
|
|
195
|
+
// @story US-001 ← テストファイルのみ（legacy 互換）
|
|
196
|
+
|
|
197
|
+
export class ConfigSchema { ... }
|
|
297
198
|
```
|
|
298
199
|
|
|
299
|
-
|
|
200
|
+
| タグ | 値 | 必須性 |
|
|
201
|
+
|---|---|---|
|
|
202
|
+
| `@unit` | `/unit-designer` が定義した Unit 名（例: `config-foundation`） | **必須**（L1-001 が検証） |
|
|
203
|
+
| `@layer` | `architecture.preset` で定義した層名（例: `domain` / `application` / `infrastructure` / `presentation`） | **必須**（L1-002 が検証） |
|
|
204
|
+
| `@work-item-id` | このファイル変更を駆動した WI（例: `WI-042`） | 任意 |
|
|
205
|
+
| `@story` | 検証する US / WI の ID（例: `US-001`, `H02-04`） | テストでは推奨（legacy 互換） |
|
|
300
206
|
|
|
301
|
-
product
|
|
207
|
+
### product 文書での反映宣言
|
|
302
208
|
|
|
303
|
-
|
|
304
|
-
<!-- docs/product/construction/my-unit/logical_design.md -->
|
|
209
|
+
product 文書（`docs/product/construction/{unit}/*.md`）の章ごとに、反映元の WI を `@work-item-id` で記載します:
|
|
305
210
|
|
|
211
|
+
```markdown
|
|
306
212
|
## ポート定義
|
|
307
213
|
|
|
308
|
-
<!-- @
|
|
309
|
-
### UserRepository Port
|
|
310
|
-
- findById(id: UserId): Promise<User>
|
|
311
|
-
|
|
312
|
-
<!-- @story-id US-001, US-002 -->
|
|
214
|
+
<!-- @work-item-id WI-042 -->
|
|
313
215
|
### OrderRepository Port
|
|
314
|
-
-
|
|
216
|
+
- findById(id: OrderId): Promise<Order>
|
|
217
|
+
|
|
218
|
+
<!-- @work-item-id WI-042, WI-051 -->
|
|
219
|
+
### PaymentGateway Port
|
|
220
|
+
- charge(amount: Money): Promise<Receipt>
|
|
315
221
|
```
|
|
316
222
|
|
|
317
|
-
|
|
223
|
+
L2-STORY-REFLECTION バリデータがこのアノテーションを検出し、inception 設計が product に反映されているかを判定します。
|
|
318
224
|
|
|
319
|
-
|
|
225
|
+
> **legacy 互換**: 既存 product 文書の `@story-id US-XXX` / `@story-id H##-##` / `@issue-id ISSUE-XXX` は、WI frontmatter の `legacy_id` 経由で読み替えられます。一括置換は **しません**。新規記述は `@work-item-id WI-XXX` を使ってください。
|
|
320
226
|
|
|
321
|
-
|
|
322
|
-
|
|
323
|
-
|
|
324
|
-
| `docs/inception/{unit}/{storyId}/domain_model.md` | `docs/product/construction/{unit}/domain_model.md` | No（警告のみ） |
|
|
227
|
+
---
|
|
228
|
+
|
|
229
|
+
## 設定の要点
|
|
325
230
|
|
|
326
|
-
|
|
231
|
+
`phasegate.config.json` が品質設定の Single Source of Truth です。**ほぼ全項目にデフォルトがあるため、まずは init が生成したものをそのまま使えば動きます**。
|
|
327
232
|
|
|
328
233
|
```jsonc
|
|
329
234
|
{
|
|
330
|
-
"
|
|
331
|
-
|
|
332
|
-
|
|
333
|
-
|
|
334
|
-
|
|
335
|
-
|
|
336
|
-
|
|
337
|
-
|
|
338
|
-
|
|
339
|
-
|
|
340
|
-
|
|
341
|
-
"inception": "docs/inception/{unit}/{storyId}/domain_model.md",
|
|
342
|
-
"product": "docs/product/construction/{unit}/domain_model.md",
|
|
343
|
-
"required": true
|
|
344
|
-
}
|
|
345
|
-
]
|
|
346
|
-
}
|
|
347
|
-
}
|
|
235
|
+
"project": { "name": "my-project", "preset": "standard" },
|
|
236
|
+
"architecture": { "preset": "clean" },
|
|
237
|
+
"layers": {
|
|
238
|
+
"L0": { "enabled": false }, "L1": { "enabled": true },
|
|
239
|
+
"L2": { "enabled": true }, "L3": { "enabled": true },
|
|
240
|
+
"L4": { "enabled": false }
|
|
241
|
+
},
|
|
242
|
+
"phaseDependencies": { "preset": "standard", "storyReflection": { "enabled": true } },
|
|
243
|
+
"quickMode": { "allowedCategories": ["bugfix", "docs", "test", "config"] },
|
|
244
|
+
"protectedFiles": { "exclude": ["package.json"] },
|
|
245
|
+
"baseline": { "enabled": true, "path": ".phasegate/baseline.json" }
|
|
348
246
|
}
|
|
349
247
|
```
|
|
350
248
|
|
|
351
|
-
|
|
352
|
-
|
|
353
|
-
- **特定の US だけゲートを通すことはできません** — inception に存在する全 US の反映が必要です
|
|
354
|
-
- `/story-implementor --story US-001` の `--story` 引数はゲートに接続されていません。検出はファイルシステムの走査のみで行われます
|
|
355
|
-
|
|
356
|
-
### quickMode -- 軽微な変更の緩和
|
|
357
|
-
|
|
358
|
-
Quick Mode は以下の方法で発動します:
|
|
249
|
+
### 3 系統の preset（呼称分離）
|
|
359
250
|
|
|
360
|
-
|
|
361
|
-
- **スキル**: `/quick-implementor` を使用すると自動で Quick Mode が適用されます
|
|
251
|
+
phasegate には独立した 3 系統の preset があります。役割が違うので呼び分けます。
|
|
362
252
|
|
|
363
|
-
|
|
364
|
-
|
|
365
|
-
|
|
366
|
-
|
|
367
|
-
|
|
|
368
|
-
|---|---|
|
|
369
|
-
| 複数カテゴリが混在する変更（例: `bugfix` + `api`） | `mixedCategories` |
|
|
370
|
-
| `domain/` 配下に新規ファイルを追加 | `newDomainFile` |
|
|
371
|
-
| `*port.ts` / `*adapter.ts`（API 契約）を変更 | `apiContractChange` |
|
|
253
|
+
| 呼称 | 設定キー | 値 | 役割 |
|
|
254
|
+
|---|---|---|---|
|
|
255
|
+
| **防御プリセット** | `project.preset` | `minimal` / `standard` / `strict` | 有効レイヤーとカバレッジ閾値を決める |
|
|
256
|
+
| **アーキプリセット** | `architecture.preset` | `clean` / `strict-ddd` / `onion` / `hexagonal` / `layered` / `flat` / `custom` | L1 が検査する層構造と依存方向 |
|
|
257
|
+
| **フェーズプリセット** | `phaseDependencies.preset` | `full` / `standard` / `minimal` / `custom` | フェーズゲートの厳密度 |
|
|
372
258
|
|
|
373
|
-
|
|
259
|
+
`npx phasegate init --preset <id>` の `--preset` は **フェーズプリセット**（`full / standard / minimal / custom`）を設定します。`project.preset` の `strict` は別概念です。
|
|
374
260
|
|
|
375
|
-
|
|
261
|
+
選定ガイド: [Preset Selection Guide](docs/guide/preset-selection.md)
|
|
376
262
|
|
|
377
|
-
|
|
263
|
+
### 主要キー
|
|
378
264
|
|
|
379
|
-
|
|
|
265
|
+
| キー | 効果 |
|
|
380
266
|
|---|---|
|
|
381
|
-
| `
|
|
382
|
-
| `package
|
|
383
|
-
| `
|
|
384
|
-
| `
|
|
267
|
+
| `quickMode.fullModeRequiredWhen` | Quick Mode → Full Mode への強制エスカレート条件（複数カテゴリ混在 / 新規ドメインファイル / API 契約変更）。安全側の default は全 `true` |
|
|
268
|
+
| `protectedFiles.exclude` | デフォルト保護対象（`package.json`, `tsconfig.json`, `biome.json` 等）から除外したいファイル |
|
|
269
|
+
| `baseline.enabled` | 既存リポジトリ導入時の retrofit grandfather。default `true`。`npx phasegate baseline` で snapshot 生成 |
|
|
270
|
+
| `phaseDependencies.storyReflection` | inception 設計が product docs に反映されるまで `src/{unit}/` への書き込みをブロック |
|
|
385
271
|
|
|
386
|
-
|
|
272
|
+
詳細: [Configuration Guide](docs/guide/configuration.md)
|
|
387
273
|
|
|
388
274
|
---
|
|
389
275
|
|
|
390
|
-
## CLI
|
|
276
|
+
## CLI 主要コマンド
|
|
391
277
|
|
|
392
278
|
```bash
|
|
393
279
|
npx phasegate <command> [options]
|
|
394
280
|
```
|
|
395
281
|
|
|
396
|
-
### セットアップ
|
|
397
|
-
|
|
398
282
|
| コマンド | 説明 |
|
|
399
283
|
|---|---|
|
|
400
|
-
| `init --name <name>` |
|
|
284
|
+
| `init --name <name>` | 初期化（skills/config/hooks 配置）。`--agent claude\|codex\|both`、`--with-husky`、`--preset <full\|standard\|minimal\|custom>` |
|
|
401
285
|
| `update-skills` | スキルを最新版に再デプロイ |
|
|
402
|
-
| `
|
|
403
|
-
| `
|
|
404
|
-
|
|
405
|
-
|
|
406
|
-
|
|
407
|
-
|
|
|
408
|
-
|---|---|---|---|
|
|
409
|
-
| `agentLessonCollection` | AI エージェントの学習ログを収集 | off (`strict` で on) | ✅ 実装済（agent-integration unit の `harness-config-config-query-adapter.ts:86` で参照、pre-tool-use hook 経路で機能） |
|
|
410
|
-
| `cascadeUpdate` | 下位フェーズの変更を上位設計に反映 | off | ✅ 実装済（`CascadeUpdateService` 経由で `skill:apply-cascade-update` CLI / cascade-updater skill が動作） |
|
|
411
|
-
| `bundleSizeLimit` | バンドルサイズ制限チェック (`number`、単位は KB) | `0` (off) / `strict` で `500` | ✅ 実装済（L3-002 performance validator が threshold として参照） |
|
|
412
|
-
| `deadCodeGC` | デッドコード検出 | off (`strict` で on) | ✅ 実装済（L4 `dead-code-detection-service` が threshold 経由で受領） |
|
|
413
|
-
|
|
414
|
-
> **補足**: 過去のバージョンでは「Feature flags のランタイム動作未実装」と記載していましたが、`v0.110.0` 時点では上表のとおり 4 機能とも実 runtime で動作します。
|
|
415
|
-
|
|
416
|
-
### 品質チェック
|
|
417
|
-
|
|
418
|
-
| コマンド | 説明 | 主なオプション |
|
|
419
|
-
|---|---|---|
|
|
420
|
-
| `lint` | L1 Biome AST チェック | `--target <path>` `--json` |
|
|
421
|
-
| `validate` | 指定レイヤーのバリデータ実行 | `--layer L1\|L2\|L3\|L4\|all` `--unit <name>` `--format human\|agent\|ci` |
|
|
422
|
-
| `ci-check` | CI フルチェック (L2-L4) | `--quick` `--dry-run` `--fail-on-reject` |
|
|
423
|
-
| `check-phase-gate` | フェーズゲートチェック | `--level 1\|2\|3` |
|
|
424
|
-
| `validate-metadata <files>` | メタデータ検証 | |
|
|
425
|
-
| `check-change-category` | 変更ファイルを Quick Mode カテゴリに分類し、`quickMode.fullModeRequiredWhen` 評価結果（Full Mode 強制が必要か）を返す（v0.63.0 / ISSUE-006 Story A） | `--paths <csv>` `--format human\|json` `--fail-on-full-required` |
|
|
426
|
-
| `baseline` | `.phasegate/baseline.json` スナップショットを生成（Phase A-2 grandfather）。登録済みファイルは構造的に編集されるまで `phase-gate` 対象から除外される（v0.65.0 / ISSUE-007 Wave 1、v0.71.0 で `baseline.enabled` default=`true`・dry-run 出力キー `files` に統一） | `--dry-run` `--force` `--paths <glob,glob,...>` `--json` |
|
|
427
|
-
| `scaffold-design --unit <id> --phase <logical\|domain\|uiux\|unit-test\|it-test>` | `templates/*.template.md` を読み取り `{{unit}}` を `--unit` 値に置換して `docs/product/construction/{unit}/*.md` に出力。phase-gate エラーに挿入される `scaffold: ...` 行の実体（v0.69.0 / ISSUE-007 Wave 4） | `--force` `--json` |
|
|
428
|
-
|
|
429
|
-
### phasegate コマンド
|
|
430
|
-
|
|
431
|
-
`phasegate:` プレフィックス付きのコマンドは JSON 出力に対応し、スクリプトからの利用に適しています。
|
|
432
|
-
|
|
433
|
-
| コマンド | 説明 |
|
|
434
|
-
|---|---|
|
|
286
|
+
| `lint` | L1 Biome AST チェック |
|
|
287
|
+
| `validate --layer <L1\|L2\|L3\|L4\|all>` | 指定レイヤーのバリデータ実行（`--format human\|agent\|ci`） |
|
|
288
|
+
| `ci-check` | CI フルチェック（L2-L4）。`--quick` で Quick Mode |
|
|
289
|
+
| `check-change-category --paths <csv>` | 変更ファイルを Quick Mode カテゴリに分類、Full Mode 強制が必要かを返す |
|
|
290
|
+
| `baseline` | retrofit grandfather snapshot 生成（`--dry-run`, `--force`, `--paths <glob>`, `--json`） |
|
|
291
|
+
| `scaffold-design --unit <id> --phase <logical\|domain\|uiux\|unit-test\|it-test>` | 最小構成の設計文書を `templates/` から生成 |
|
|
435
292
|
| `phasegate:status` | 全体の健全性サマリ |
|
|
436
|
-
| `phasegate:check-ready` | 全 story の Phase Gate 通過状態 |
|
|
437
293
|
| `phasegate:check-phase --unit <id>` | 指定 Unit の現在フェーズ |
|
|
438
|
-
| `phasegate:ci-check` | 全 L3 バリデータ実行 |
|
|
439
294
|
| `phasegate:detect-drift` | 設計-コード乖離レポート |
|
|
440
|
-
| `
|
|
441
|
-
| `
|
|
442
|
-
| `
|
|
443
|
-
|
|
444
|
-
|
|
445
|
-
|
|
446
|
-
| コマンド | 説明 |
|
|
447
|
-
|---|---|
|
|
448
|
-
| `list-adrs` | ADR 一覧（`--status` でフィルタ可能） |
|
|
449
|
-
| `validate-adr` | ADR 検証（`--all` または `<adrRef>`） |
|
|
450
|
-
| `list-errors` | エラー定義一覧（`--layer L0-L4`） |
|
|
451
|
-
| `ci:generate-template` | CI/CD テンプレート生成（`--type <type>`） |
|
|
452
|
-
| `migrate work-items` | `docs/inception/` 配下の旧 `ISSUE-XXX` / `H{NN}-{NN}` directory を統一 `WI-XXX` レイアウトへ移行（v0.100.0 で導入、v0.105.0 で H-ID 検出に拡張）。frontmatter に `type` / `legacy_id` / `affects` を注入し、空き番号の若い順に sequential 採番（既存 WI 番号は予約）。`--dry-run` / `--apply` / `--json`。詳細は [CLI Reference -- Work Item Migration](docs/guide/cli-reference.md#work-item-migration) |
|
|
453
|
-
| `migrate --schema v3` | `phasegate.config.json` を v3 スキーマへ昇格（`architecture` キーを追加、既存設定は保持）。冪等。 |
|
|
454
|
-
|
|
455
|
-
### Hook / 委任ラッパー
|
|
456
|
-
|
|
457
|
-
| コマンド | 説明 |
|
|
458
|
-
|---|---|
|
|
459
|
-
| `hook <pre-tool-use\|post-tool-use\|stop>` | Claude Code hook を起動（stdin から JSON を読む） |
|
|
460
|
-
| `pre-commit` | L2 pre-commit バリデータをステージファイルに対して実行 |
|
|
461
|
-
| `delegate-sonnet [...args]` | Sonnet 4.6 委任スクリプトの透過ラッパー（`scripts/delegate-sonnet.sh` に引数を forward） |
|
|
295
|
+
| `migrate work-items --dry-run` / `--apply` | 既存リポジトリの旧 `ISSUE-XXX` / `H{NN}-{NN}` directory を WI 統一レイアウト（`_cross/{WI-XXX}/` / `{unit}/{WI-XXX}/`）へ移行。frontmatter（`type` / `severity` / `legacy_id` / `affects`）を自動注入。冪等。`--json` で CI/スクリプト連携可。詳細: [Work Item Migration](docs/guide/cli-reference.md#work-item-migration) |
|
|
296
|
+
| `migrate --schema v3` | `phasegate.config.json` を v3 schema へ昇格（`architecture` キー追加） |
|
|
297
|
+
| `ci:generate-template --type <aidlc-gate\|pre-commit\|consistency-check>` | CI/CD テンプレート生成（`--render` でファイル出力） |
|
|
298
|
+
| `list-errors --layer <L0-L4>` | エラー定義一覧 |
|
|
299
|
+
| `hook <pre-tool-use\|post-tool-use\|stop>` | agent hook を起動（stdin から JSON） |
|
|
300
|
+
| `pre-commit` | L2 pre-commit バリデータをステージファイルに適用 |
|
|
462
301
|
|
|
463
|
-
|
|
302
|
+
完全な CLI Reference: [CLI Reference](docs/guide/cli-reference.md)
|
|
464
303
|
|
|
465
304
|
---
|
|
466
305
|
|
|
467
|
-
##
|
|
306
|
+
## Hooks 統合
|
|
468
307
|
|
|
469
|
-
|
|
308
|
+
### Claude Code
|
|
470
309
|
|
|
471
|
-
|
|
472
|
-
|
|
473
|
-
Claude Code セッション内でスラッシュコマンドとして実行します:
|
|
474
|
-
|
|
475
|
-
```
|
|
476
|
-
/product-architect ← Level 1 の最初のスキル
|
|
477
|
-
/story-implementor ← Level 3 の実装スキル
|
|
478
|
-
/quick-implementor ← バグ修正など軽微な変更
|
|
479
|
-
```
|
|
480
|
-
|
|
481
|
-
各スキルは前のレベルの成果物を入力として参照します。前提条件が未完了の場合、フェーズゲートがブロックします。
|
|
482
|
-
|
|
483
|
-
### Level 1: 要求定義（成果物: `docs/inception/_shared/`）
|
|
484
|
-
|
|
485
|
-
| スキル | 目的 |
|
|
486
|
-
|---|---|
|
|
487
|
-
| `/product-architect` | プロダクト全体像（ドメイン・アーキテクチャ・制約）を定義 |
|
|
488
|
-
| `/story-writer` | Who/What/Why 形式のユーザーストーリーと受け入れ基準を作成 |
|
|
489
|
-
| `/story-mapper` | MVP スコープ整理・優先順位定義 |
|
|
490
|
-
| `/unit-designer` | ストーリーを独立構築可能な Unit にグルーピング |
|
|
491
|
-
|
|
492
|
-
### Level 2: Unit 設計（成果物: `docs/inception/{unit}/`）
|
|
493
|
-
|
|
494
|
-
Level 1 の `/unit-designer` 完了が前提条件。
|
|
495
|
-
|
|
496
|
-
| スキル | 目的 |
|
|
497
|
-
|---|---|
|
|
498
|
-
| `/domain-designer` | DDD ドメインモデル設計（集約・Entity・VO・イベント） |
|
|
499
|
-
| `/logical-designer` | Hexagonal Architecture 設計（Port & Adapter） |
|
|
500
|
-
| `/mock-designer` | UI モックアップ設計 |
|
|
501
|
-
| `/environment-designer` | ローカル開発環境・インフラ設計 |
|
|
502
|
-
| `/unit-test-designer` | ユニットテストケース設計 |
|
|
503
|
-
| `/it-test-designer` | 統合テストケース設計 |
|
|
504
|
-
| `/unit-test-logic-designer` | UT Vitest 実装ロジック設計 |
|
|
505
|
-
| `/it-test-logic-designer` | IT Vitest 実装ロジック設計 |
|
|
310
|
+
`init` が `.claude/settings.json` に以下を配置します。
|
|
506
311
|
|
|
507
|
-
|
|
508
|
-
|
|
509
|
-
Level 2 の `domain_model.md` + `logical_design.md` の存在が前提条件。
|
|
510
|
-
|
|
511
|
-
| スキル | 目的 |
|
|
512
|
-
|---|---|
|
|
513
|
-
| `/logical-designer` | US 固有の論理設計 |
|
|
514
|
-
| `/uiux-designer` | 最終 UI/UX 定義 |
|
|
515
|
-
| `/scenario-test-designer` | E2E シナリオテストケース設計 |
|
|
516
|
-
| `/scenario-test-logic-designer` | Playwright E2E 実装ロジック設計 |
|
|
517
|
-
| `/implementation-readiness-checker` | 実装開始前の準備状況検証 |
|
|
518
|
-
| `/story-implementor` | TDD 実装 (Red -> Green -> Refactor) |
|
|
519
|
-
| `/quick-implementor` | 軽微変更の高速実装（バグ修正・ドキュメント等） |
|
|
520
|
-
|
|
521
|
-
### Verification スキル（任意のタイミングで使用）
|
|
522
|
-
|
|
523
|
-
| スキル | 目的 |
|
|
524
|
-
|---|---|
|
|
525
|
-
| `/consistency-checker` | 設計文書間の整合性チェック |
|
|
526
|
-
| `/cascade-updater` | 下位フェーズの発見を上位設計にフィードバック ※未完成 |
|
|
527
|
-
| `/codex-delegator` | Codex CLI にタスクを委任し品質管理 |
|
|
528
|
-
| `/codebase-mapper` | `@unit`/`@layer` アノテーションから構造マップ生成 |
|
|
529
|
-
| `/doc-freshness-checker` | 設計文書の鮮度チェック |
|
|
530
|
-
| `/pointer-validator` | 設計文書内のファイルパス参照を検証 |
|
|
531
|
-
| `/engineering-perspective` | Beck/Fowler/Martin/Evans の視点で設計レビュー |
|
|
532
|
-
| `/test-coverage-checker` | カバレッジ検証・Nyquist Validation |
|
|
533
|
-
| `/implementation-planner` | 実装計画の立案 |
|
|
534
|
-
| `/skill-creator` | スキルの作成・更新 |
|
|
535
|
-
|
|
536
|
-
---
|
|
537
|
-
|
|
538
|
-
## メタデータ規約
|
|
539
|
-
|
|
540
|
-
全ソースファイルの先頭に `@unit` / `@layer` コメントを記載します。テストファイルには `@story` も追加します。
|
|
541
|
-
|
|
542
|
-
```typescript
|
|
543
|
-
// @unit config-foundation
|
|
544
|
-
// @layer domain
|
|
545
|
-
// @story US-001 ← テストファイルのみ
|
|
546
|
-
|
|
547
|
-
export class ConfigSchema { ... }
|
|
548
|
-
```
|
|
549
|
-
|
|
550
|
-
| タグ | 値の決め方 | 例 |
|
|
312
|
+
| Hook | タイミング | 動作 |
|
|
551
313
|
|---|---|---|
|
|
552
|
-
|
|
|
553
|
-
|
|
|
554
|
-
|
|
|
555
|
-
|
|
556
|
-
これにより L1 検証（`require-unit-comment`, `require-layer-comment`）・トレーサビリティ・drift-detection が機能します。タグが欠けているファイルは L1 でエラーになります（`layers.L1.rules` で緩和可能）。
|
|
557
|
-
|
|
558
|
-
---
|
|
559
|
-
|
|
560
|
-
## Claude Code Hooks
|
|
314
|
+
| **PreToolUse** | Write/Edit/Bash の実行前 | フェーズゲート違反 / 保護ファイル / Bash 経由迂回をブロック。Quick→Full 強制条件のチェックも実行 |
|
|
315
|
+
| **PostToolUse** | Write/Edit の実行後 | Biome AST ルールを自動実行、違反を即時フィードバック |
|
|
316
|
+
| **Stop** | セッション終了前 | L2-L4 全チェックを実行、グリーンでないと終了を保留 |
|
|
561
317
|
|
|
562
|
-
|
|
318
|
+
### Codex CLI
|
|
563
319
|
|
|
564
|
-
|
|
565
|
-
{
|
|
566
|
-
"hooks": {
|
|
567
|
-
"PreToolUse": [
|
|
568
|
-
{
|
|
569
|
-
"matcher": "Write|Edit|Bash",
|
|
570
|
-
"hooks": [{
|
|
571
|
-
"type": "command",
|
|
572
|
-
"command": "npx tsx scripts/harness/agent-integration/presentation/pre-tool-use-hook.ts"
|
|
573
|
-
}]
|
|
574
|
-
}
|
|
575
|
-
],
|
|
576
|
-
"PostToolUse": [
|
|
577
|
-
{
|
|
578
|
-
"matcher": "Write|Edit",
|
|
579
|
-
"hooks": [{
|
|
580
|
-
"type": "command",
|
|
581
|
-
"command": "npx tsx scripts/harness/agent-integration/presentation/post-tool-use-hook.ts"
|
|
582
|
-
}]
|
|
583
|
-
}
|
|
584
|
-
],
|
|
585
|
-
"Stop": [
|
|
586
|
-
{
|
|
587
|
-
"matcher": "",
|
|
588
|
-
"hooks": [{
|
|
589
|
-
"type": "command",
|
|
590
|
-
"command": "npx tsx scripts/harness/agent-integration/presentation/stop-hook.ts"
|
|
591
|
-
}]
|
|
592
|
-
}
|
|
593
|
-
]
|
|
594
|
-
}
|
|
595
|
-
}
|
|
596
|
-
```
|
|
320
|
+
`init --agent codex` で `.codex/hooks.json` を配置。Codex のネイティブ `apply_patch` ツールは hook を発火しないため（[openai/codex#16732](https://github.com/openai/codex/issues/16732)）、ネイティブ経路は **pre-commit (L2)** で commit 時にブロックされます。
|
|
597
321
|
|
|
598
|
-
|
|
|
322
|
+
| 編集経路 | 事前 hard block | commit 時 block |
|
|
599
323
|
|---|---|---|
|
|
600
|
-
|
|
|
601
|
-
|
|
|
602
|
-
|
|
|
324
|
+
| Bash 書き込み（`sed -i`, `tee`, heredoc, `cat >`） | ✅ PreToolUse(Bash) | ✅ pre-commit |
|
|
325
|
+
| Bash 経由 `apply_patch <<'PATCH'` | ✅ PreToolUse(Bash) | ✅ pre-commit |
|
|
326
|
+
| Codex ネイティブ `apply_patch` | ❌ Codex 側の制約で hook 非発火 | ✅ pre-commit |
|
|
603
327
|
|
|
604
|
-
|
|
328
|
+
**推奨運用**: こまめに commit して pre-commit でネイティブ `apply_patch` 違反を早期に surface する。
|
|
605
329
|
|
|
606
|
-
|
|
330
|
+
詳細: [Hooks Integration](docs/guide/hooks-integration.md) ・ [Codex Integration](docs/guide/codex-integration.md)
|
|
607
331
|
|
|
608
332
|
---
|
|
609
333
|
|
|
610
|
-
##
|
|
334
|
+
## ドキュメント・ライフサイクル
|
|
611
335
|
|
|
612
|
-
Phasegate は
|
|
336
|
+
Phasegate は **「inception で設計を起こし → product に確定させ → src に実装する」** という単方向のデータフローを物理的に強制します。各段階で生成される文書と PhaseGate の振る舞いが対応しています。
|
|
613
337
|
|
|
614
|
-
###
|
|
338
|
+
### 三階層モデル
|
|
615
339
|
|
|
616
|
-
```
|
|
617
|
-
|
|
618
|
-
|
|
619
|
-
|
|
620
|
-
|
|
621
|
-
|
|
340
|
+
```
|
|
341
|
+
docs/inception/{unit}/{WI-XXX}/ ← 一時的な計画・設計（WI ごと、流動）
|
|
342
|
+
↓ 設計成果物の反映（@work-item-id 付きで累積更新）
|
|
343
|
+
docs/product/construction/{unit}/ ← 確定設計（Unit ごとの正本、永続）
|
|
344
|
+
↕ フェーズゲート
|
|
345
|
+
scripts/harness/{unit}/(domain|application|infrastructure|presentation)/*.ts
|
|
622
346
|
```
|
|
623
347
|
|
|
624
|
-
|
|
348
|
+
### Work Item (WI) の置き場
|
|
625
349
|
|
|
626
|
-
|
|
350
|
+
WI は規模・影響範囲に応じて 3 通りに振り分けます。
|
|
627
351
|
|
|
628
|
-
|
|
352
|
+
| 配置先 | 用途 |
|
|
353
|
+
|---|---|
|
|
354
|
+
| `docs/inception/_shared/` | 非 WI の横断計画・戦略・調査メモ |
|
|
355
|
+
| `docs/inception/_cross/{WI-XXX}/` | 複数 Unit に影響する cross-cutting WI |
|
|
356
|
+
| `docs/inception/{unit}/{WI-XXX}/` | 単一 Unit が所有する WI |
|
|
629
357
|
|
|
630
|
-
|
|
358
|
+
> **廃止済み**（v0.104.0 で物理削除）: `docs/inception/issues/`, `docs/inception/{unit}/issues/`, `docs/inception/{unit}/{US-XXX}/`。既存資産は `npx phasegate migrate work-items --apply` で `WI-XXX` へ移行済み。`legacy_id` で旧 ID の grep 互換は維持。
|
|
631
359
|
|
|
632
|
-
|
|
633
|
-
|---|---|---|
|
|
634
|
-
| Bash 書き込み（`sed -i`, `tee`, heredoc, `cat >`） | ✅ `PreToolUse(Bash)` | ✅ pre-commit |
|
|
635
|
-
| Bash 経由 `apply_patch <<'PATCH'` | ✅ `PreToolUse(Bash)`（`BashWriteTargetExtractor` で heredoc 解析） | ✅ pre-commit |
|
|
636
|
-
| Codex ネイティブ `apply_patch` ツール | ❌ Codex 側の制約で hook 非発火 | ✅ pre-commit |
|
|
360
|
+
### WI frontmatter（必須）
|
|
637
361
|
|
|
638
|
-
|
|
362
|
+
各 WI の `description.md` 先頭に:
|
|
639
363
|
|
|
364
|
+
```yaml
|
|
365
|
+
---
|
|
366
|
+
id: WI-042
|
|
367
|
+
type: story | issue | fix | refactor | chore # 後述
|
|
368
|
+
severity: trivial | normal | high
|
|
369
|
+
status: drafted | reflected | implemented | tested # PhaseGate が自動更新
|
|
370
|
+
affects: [unit-a, unit-b] # cross-unit のみ列挙
|
|
371
|
+
legacy_id: ISSUE-XXX | US-XXX | H{NN}-{NN} # 任意
|
|
640
372
|
---
|
|
641
|
-
|
|
642
|
-
## カスタムフェーズゲート
|
|
643
|
-
|
|
644
|
-
デフォルトでは AIDLC フェーズ依存モデルが適用されますが、`gates[]` 配列で独自のゲートを定義できます。
|
|
645
|
-
|
|
646
|
-
### ゲート定義
|
|
647
|
-
|
|
648
|
-
| フィールド | 型 | 説明 |
|
|
649
|
-
|---|---|---|
|
|
650
|
-
| `name` | string | ゲートの一意識別子 |
|
|
651
|
-
| `level` | 1 \| 2 \| 3 | フェーズレベル（上位は下位の通過が前提） |
|
|
652
|
-
| `blocks` | string[] | 保護するファイルの glob パターン |
|
|
653
|
-
| `requires` | string[] | 書き込み前に存在が必要なファイル |
|
|
654
|
-
| `dependsOn` | string[] | 事前に通過が必要な他のゲート名 |
|
|
655
|
-
| `description` | string | ゲートの説明 |
|
|
656
|
-
|
|
657
|
-
ゲートは DAG（有向非巡回グラフ）を形成します。循環依存は設定読み込み時に拒否されます。
|
|
658
|
-
|
|
659
|
-
### 例 1: API スキーマファーストゲート
|
|
660
|
-
|
|
661
|
-
AIDLC を使わないプロジェクトで「OpenAPI スキーマなしに API 実装を書けない」を強制する例:
|
|
662
|
-
|
|
663
|
-
```jsonc
|
|
664
|
-
{
|
|
665
|
-
"phaseDependencies": {
|
|
666
|
-
"preset": "custom",
|
|
667
|
-
"override": true,
|
|
668
|
-
"gates": [
|
|
669
|
-
{
|
|
670
|
-
"name": "schema-first",
|
|
671
|
-
"level": 3,
|
|
672
|
-
"blocks": ["src/api/**/*.ts"],
|
|
673
|
-
"requires": ["docs/api/openapi.yaml"],
|
|
674
|
-
"description": "API実装にはOpenAPIスキーマが必要"
|
|
675
|
-
}
|
|
676
|
-
]
|
|
677
|
-
}
|
|
678
|
-
}
|
|
679
|
-
```
|
|
680
|
-
|
|
681
|
-
### 例 2: AIDLC フローを明示的に定義
|
|
682
|
-
|
|
683
|
-
[docs/folder_management_rules.md](docs/folder_management_rules.md) の **inception → product → source** フローを段階的にゲートする例:
|
|
684
|
-
|
|
685
|
-
```jsonc
|
|
686
|
-
{
|
|
687
|
-
"phaseDependencies": {
|
|
688
|
-
"preset": "custom",
|
|
689
|
-
"override": true,
|
|
690
|
-
"gates": [
|
|
691
|
-
// Phase 1: プロダクト概要がないとストーリー定義に進めない
|
|
692
|
-
{
|
|
693
|
-
"name": "product-overview",
|
|
694
|
-
"level": 1,
|
|
695
|
-
"blocks": [
|
|
696
|
-
"docs/product/user_stories.md",
|
|
697
|
-
"docs/product/user_story_mapping.md"
|
|
698
|
-
],
|
|
699
|
-
"requires": ["docs/product/product_overview.md"],
|
|
700
|
-
"description": "プロダクト概要がないとストーリー定義に進めない"
|
|
701
|
-
},
|
|
702
|
-
// Phase 1→2: Unit定義がないとUnit設計に進めない
|
|
703
|
-
{
|
|
704
|
-
"name": "unit-definition",
|
|
705
|
-
"level": 1,
|
|
706
|
-
"blocks": ["docs/product/construction/*/domain_model.md"],
|
|
707
|
-
"requires": ["docs/product/units/integration_contract.md"],
|
|
708
|
-
"dependsOn": ["product-overview"],
|
|
709
|
-
"description": "Unit定義・統合契約がないとUnit設計に進めない"
|
|
710
|
-
},
|
|
711
|
-
// Phase 2: ドメインモデルがないと論理設計に進めない
|
|
712
|
-
{
|
|
713
|
-
"name": "domain-model",
|
|
714
|
-
"level": 2,
|
|
715
|
-
"blocks": ["docs/product/construction/*/logical_design.md"],
|
|
716
|
-
"requires": ["docs/product/construction/{unit}/domain_model.md"],
|
|
717
|
-
"dependsOn": ["unit-definition"],
|
|
718
|
-
"description": "ドメインモデルがないと論理設計に進めない"
|
|
719
|
-
},
|
|
720
|
-
// Phase 2→3: 論理設計がないと実装コードに進めない
|
|
721
|
-
{
|
|
722
|
-
"name": "implementation-gate",
|
|
723
|
-
"level": 3,
|
|
724
|
-
"blocks": ["src/**/*.ts"],
|
|
725
|
-
"requires": [
|
|
726
|
-
"docs/product/construction/{unit}/domain_model.md",
|
|
727
|
-
"docs/product/construction/{unit}/logical_design.md"
|
|
728
|
-
],
|
|
729
|
-
"dependsOn": ["domain-model"],
|
|
730
|
-
"description": "確定版の設計文書がないと実装に進めない"
|
|
731
|
-
}
|
|
732
|
-
],
|
|
733
|
-
"storyReflection": {
|
|
734
|
-
"enabled": true,
|
|
735
|
-
"mappings": [
|
|
736
|
-
{
|
|
737
|
-
"inception": "docs/inception/{unit}/{storyId}/logical_design.md",
|
|
738
|
-
"product": "docs/product/construction/{unit}/logical_design.md",
|
|
739
|
-
"required": true
|
|
740
|
-
}
|
|
741
|
-
]
|
|
742
|
-
}
|
|
743
|
-
}
|
|
744
|
-
}
|
|
745
373
|
```
|
|
746
374
|
|
|
747
|
-
|
|
375
|
+
L2 metadata validator が frontmatter の妥当性を検証します。
|
|
748
376
|
|
|
749
|
-
|
|
750
|
-
product_overview.md
|
|
751
|
-
→ user_stories.md / user_story_mapping.md
|
|
752
|
-
→ integration_contract.md
|
|
753
|
-
→ domain_model.md
|
|
754
|
-
→ logical_design.md
|
|
755
|
-
→ src/**/*.ts（+ storyReflection で US 単位の反映も必須）
|
|
756
|
-
```
|
|
377
|
+
### type による要求成果物の段階化
|
|
757
378
|
|
|
758
|
-
|
|
379
|
+
| `type` | inception 必須 | product 反映 | 用途 |
|
|
380
|
+
|---|---|---|---|
|
|
381
|
+
| `story` | description + logical_design + domain_model + test 設計 | 全カテゴリ累積 | 新機能 |
|
|
382
|
+
| `issue` | description + logical_design + domain_model + 関係 test 設計 | 関係カテゴリ累積 | バグ・仕様不整合 |
|
|
383
|
+
| `refactor` | description + logical_design | logical_design 更新 | リファクタ |
|
|
384
|
+
| `fix` | description + PR link | 関係カテゴリに `@work-item-id` 追記 | typo・依存更新等 |
|
|
385
|
+
| `chore` | description.md 1 行 + PR link | 不要 | 雑用 |
|
|
759
386
|
|
|
760
|
-
|
|
387
|
+
`fix` / `chore` は軽量パスとして提供。formal な story で起票するには重すぎる修正もここで証跡が残せます。
|
|
761
388
|
|
|
762
|
-
|
|
389
|
+
### State Machine
|
|
763
390
|
|
|
764
|
-
```bash
|
|
765
|
-
npx phasegate ci:generate-template --type aidlc-gate # PR検証ワークフロー
|
|
766
|
-
npx phasegate ci:generate-template --type pre-commit # Pre-commitフック
|
|
767
|
-
npx phasegate ci:generate-template --type consistency-check # 週次整合性チェック
|
|
768
391
|
```
|
|
769
|
-
|
|
770
|
-
|
|
771
|
-
|
|
772
|
-
|
|
773
|
-
|
|
392
|
+
DRAFTED (inception 揃う)
|
|
393
|
+
↓ Phase 0/2 reflection
|
|
394
|
+
REFLECTED (product に @work-item-id 反映済み)
|
|
395
|
+
↓ Phase 3 implementation
|
|
396
|
+
IMPLEMENTED (src 実装あり / lint・type・test green)
|
|
397
|
+
↓ Phase 4 test
|
|
398
|
+
TESTED (@work-item-id 付きテストあり / green)
|
|
774
399
|
```
|
|
775
400
|
|
|
776
|
-
|
|
401
|
+
`type: chore` は DRAFTED で完結。`type: fix` は DRAFTED → REFLECTED → IMPLEMENTED の簡略パス。`status` は PhaseGate が自動更新します。
|
|
402
|
+
|
|
403
|
+
詳細仕様: [`docs/folder_management_rules.md`](docs/folder_management_rules.md)
|
|
777
404
|
|
|
778
405
|
---
|
|
779
406
|
|
|
@@ -781,62 +408,78 @@ npx phasegate ci:generate-template --type aidlc-gate --render > .github/workflow
|
|
|
781
408
|
|
|
782
409
|
```
|
|
783
410
|
your-project/
|
|
784
|
-
├── phasegate.config.json
|
|
411
|
+
├── phasegate.config.json
|
|
785
412
|
├── docs/
|
|
786
|
-
│ ├── folder_management_rules.md
|
|
787
|
-
│ ├── principles/
|
|
788
|
-
│ ├──
|
|
789
|
-
│ │ ├──
|
|
413
|
+
│ ├── folder_management_rules.md # WI 仕様の正本（init で配置）
|
|
414
|
+
│ ├── principles/ # 開発原則（init で配置・immutable）
|
|
415
|
+
│ ├── inception/ # AIDLC スキルが生成
|
|
416
|
+
│ │ ├── _shared/ # 横断計画
|
|
417
|
+
│ │ ├── _cross/{WI-XXX}/ # cross-unit WI
|
|
418
|
+
│ │ └── {unit}/{WI-XXX}/ # Unit 所有 WI
|
|
419
|
+
│ ├── product/ # 確定設計（累積更新）
|
|
420
|
+
│ │ ├── product_overview.md
|
|
421
|
+
│ │ ├── user_stories.md
|
|
790
422
|
│ │ ├── units/{unit}.md
|
|
791
423
|
│ │ └── construction/{unit}/
|
|
792
424
|
│ │ ├── domain_model.md
|
|
793
|
-
│ │
|
|
794
|
-
│
|
|
795
|
-
│ │ ├── _shared/ # Level 1（プロダクト全体）
|
|
796
|
-
│ │ └── {unit}/{US-XXX}/ # Level 2/3（Unit・ストーリー単位）
|
|
425
|
+
│ │ ├── logical_design.md
|
|
426
|
+
│ │ └── ...
|
|
797
427
|
│ └── ADR/
|
|
798
|
-
├── src/
|
|
799
|
-
├── .claude/
|
|
800
|
-
|
|
801
|
-
|
|
802
|
-
├── .codex/
|
|
803
|
-
│ ├── hooks.json # Codex hooks 設定
|
|
804
|
-
│ └── skills/ # ../skills への symlink（Codex有効時）
|
|
805
|
-
└── skills/ # npx phasegate init で再生成可能
|
|
428
|
+
├── src/ # 実装コード（@unit/@layer 必須）
|
|
429
|
+
├── .claude/{settings.json, skills/}
|
|
430
|
+
├── .codex/{hooks.json, skills/} # --agent codex|both 時
|
|
431
|
+
└── skills/ # init で再生成可能
|
|
806
432
|
```
|
|
807
433
|
|
|
808
|
-
|
|
434
|
+
推奨 `.gitignore`:
|
|
809
435
|
|
|
810
436
|
```
|
|
811
437
|
node_modules/
|
|
812
|
-
skills/ #
|
|
813
|
-
.claude/skills/ #
|
|
814
|
-
.codex/skills/ #
|
|
438
|
+
skills/ # init で再生成可能
|
|
439
|
+
.claude/skills/ # symlink
|
|
440
|
+
.codex/skills/ # symlink
|
|
815
441
|
dist/
|
|
816
442
|
reports/
|
|
817
443
|
```
|
|
818
444
|
|
|
819
445
|
---
|
|
820
446
|
|
|
821
|
-
##
|
|
447
|
+
## ロードマップ
|
|
822
448
|
|
|
823
|
-
|
|
449
|
+
ドキュメントで言及があるが現状 partial 実装または user 配線に依存しているもの。各 Work Item は `docs/inception/_cross/WI-XXX/description.md` に起票済み。
|
|
824
450
|
|
|
825
|
-
| Work Item |
|
|
826
|
-
|
|
827
|
-
| **[WI-031](docs/inception/_cross/WI-031/description.md)** | CI template の二系統統一 + `phasegate init --with-ci` |
|
|
828
|
-
| **[WI-032](docs/inception/_cross/WI-032/description.md)** | AGENTS.md / CLAUDE.md auto-refresh パイプライン |
|
|
829
|
-
| **[WI-033](docs/inception/_cross/WI-033/description.md)** | `doc-freshness` / `pointer-validation` を L4 validator に昇格 |
|
|
830
|
-
| **[WI-034](docs/inception/_cross/WI-034/description.md)** | L0 legacy validator (`L0-001` / `L0-002`) の撤去 |
|
|
451
|
+
| Work Item | 内容 |
|
|
452
|
+
|---|---|
|
|
453
|
+
| **[WI-031](docs/inception/_cross/WI-031/description.md)** | CI template の二系統統一 + `phasegate init --with-ci` |
|
|
454
|
+
| **[WI-032](docs/inception/_cross/WI-032/description.md)** | AGENTS.md / CLAUDE.md auto-refresh パイプライン |
|
|
455
|
+
| **[WI-033](docs/inception/_cross/WI-033/description.md)** | `doc-freshness` / `pointer-validation` を L4 validator に昇格 |
|
|
456
|
+
| **[WI-034](docs/inception/_cross/WI-034/description.md)** | L0 legacy validator (`L0-001` / `L0-002`) の撤去 |
|
|
457
|
+
|
|
458
|
+
L3 Nyquist Validation の `requirement-test-matrix.json` 自動生成パイプラインも未完成（手動セットアップで利用可）。
|
|
459
|
+
|
|
460
|
+
---
|
|
461
|
+
|
|
462
|
+
## ドキュメント
|
|
463
|
+
|
|
464
|
+
- [Installation](docs/guide/installation.md) — 詳細インストール手順
|
|
465
|
+
- [Configuration](docs/guide/configuration.md) — `phasegate.config.json` 完全リファレンス
|
|
466
|
+
- [CLI Reference](docs/guide/cli-reference.md) — 全 CLI コマンド・オプション
|
|
467
|
+
- [Skills Overview](docs/guide/skills-overview.md) — 28 スキルの実行順序と成果物
|
|
468
|
+
- [5-Layer Defense Model](docs/guide/layer-model.md) — L0-L4 詳細・HarnessError 形式
|
|
469
|
+
- [Hooks Integration](docs/guide/hooks-integration.md) — Claude Code Hooks 設定
|
|
470
|
+
- [Codex Integration](docs/guide/codex-integration.md) — Codex CLI セットアップ・カバレッジ
|
|
471
|
+
- [Quick Mode vs Full Mode](docs/guide/quick-vs-full-mode.md) — `/story-implementor` vs `/quick-implementor`
|
|
472
|
+
- [Retrofit Adoption Guide](docs/guide/retrofit-adoption.md) — 既存リポジトリへの段階的導入
|
|
473
|
+
- [Preset Selection Guide](docs/guide/preset-selection.md) — 3 系統の preset 選定
|
|
831
474
|
|
|
832
|
-
|
|
475
|
+
phasegate 自体の開発: [DEVELOPMENT.ja.md](DEVELOPMENT.ja.md)
|
|
833
476
|
|
|
834
477
|
---
|
|
835
478
|
|
|
836
|
-
##
|
|
479
|
+
## ライセンス
|
|
837
480
|
|
|
838
|
-
|
|
481
|
+
[MIT License](LICENSE)
|
|
839
482
|
|
|
840
483
|
---
|
|
841
484
|
|
|
842
|
-
*Last updated: 2026-04-25
|
|
485
|
+
*Last updated: 2026-04-25 — v0.110.0*
|