phasegate 0.110.0 → 0.111.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 +224 -696
- package/README.md +2 -2
- package/package.json +2 -2
package/README.ja.md
CHANGED
|
@@ -1,779 +1,301 @@
|
|
|
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
|
-
##
|
|
42
|
-
|
|
43
|
-
### 前提条件
|
|
44
|
-
|
|
45
|
-
Node.js >= 18, npm >= 9, TypeScript 5.x
|
|
46
|
-
|
|
47
|
-
### 1. インストール
|
|
23
|
+
## なぜ Phasegate か
|
|
48
24
|
|
|
49
|
-
|
|
50
|
-
npm install --save-dev phasegate
|
|
51
|
-
```
|
|
25
|
+
AI agent は速いが、設計を飛ばして実装に走ります。レイヤー境界を平気で越え、`any` 型で型システムを骨抜きにし、テストはあるけど実装の写経になっている — そんなコードを高速に量産します。レビューで全部捕まえるのは現実的ではありません。
|
|
52
26
|
|
|
53
|
-
|
|
27
|
+
Phasegate はこれを **「人がレビューで防ぐ」のではなく「ツールがファイルシステム/git/CI レベルで防ぐ」** で解決します。設計文書がなければそもそも書けない。レイヤー違反があれば commit が通らない。AI agent 自身が「次にどの設計スキルを呼べばいいか」を読んで自走します。
|
|
54
28
|
|
|
55
|
-
|
|
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
|
-
|
|
81
|
-
|
|
82
|
-
## 5層防御モデル
|
|
83
|
-
|
|
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` |
|
|
54
|
+
Claude Code / Codex はこのメッセージを読んで `/story-implementor` を起動し、ドメイン設計→論理設計→TDD 実装の順で進みます。人間が「設計やってからね」と言わなくても自走します。
|
|
91
55
|
|
|
92
|
-
|
|
56
|
+
---
|
|
93
57
|
|
|
94
|
-
|
|
58
|
+
## クイックスタート
|
|
95
59
|
|
|
96
|
-
|
|
60
|
+
### 前提
|
|
97
61
|
|
|
98
|
-
|
|
99
|
-
|---|---|---|
|
|
100
|
-
| `human` | ローカル開発 | コンソール向け（絵文字・色付き） |
|
|
101
|
-
| `agent` | AI エージェント連携 | キー値テキスト（`OVERALL: PASS`, `VALIDATOR: L2-001`） |
|
|
102
|
-
| `ci` | CI/CD パイプライン | 構造化 JSON（GitHub Actions 等で解析可能） |
|
|
62
|
+
Node.js >= 18, npm >= 9, TypeScript 5.x
|
|
103
63
|
|
|
104
|
-
###
|
|
64
|
+
### 3 ステップ
|
|
105
65
|
|
|
106
|
-
|
|
66
|
+
```bash
|
|
67
|
+
# 1. インストール
|
|
68
|
+
npm install --save-dev phasegate
|
|
107
69
|
|
|
108
|
-
|
|
109
|
-
|
|
110
|
-
| **日本語テスト名** | L2-003 | `it()` / `test()` のテスト名が日本語であること |
|
|
111
|
-
| **`actual` 変数** | L2-003 | `expect()` の対象を `const actual` に代入していること |
|
|
112
|
-
| **CLI E2E テスト存在** | L2-013 | CLI コマンドに対応する E2E テストが存在すること |
|
|
70
|
+
# 2. プロジェクトを初期化
|
|
71
|
+
npx phasegate init --name my-project --with-husky
|
|
113
72
|
|
|
114
|
-
|
|
115
|
-
|
|
116
|
-
|
|
117
|
-
// Arrange
|
|
118
|
-
const userId = "test_user";
|
|
119
|
-
|
|
120
|
-
// Act
|
|
121
|
-
const actual = await sut.findByUserId(userId);
|
|
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
|
-
});
|
|
73
|
+
# 3. AI agent を起動して /product-architect から始める
|
|
74
|
+
claude
|
|
75
|
+
> /product-architect
|
|
132
76
|
```
|
|
133
77
|
|
|
134
|
-
|
|
135
|
-
|
|
136
|
-
> **注意**: バリデーションロジックは実装済みですが、マトリクスファイルの自動生成パイプラインが未完成のため、現時点では手動セットアップが必要です。
|
|
78
|
+
`init` が生成するもの:
|
|
137
79
|
|
|
138
|
-
|
|
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
|
+
- `docs/principles/` ・ `docs/folder_management_rules.md` — 設計原則 docs
|
|
85
|
+
- `--with-husky` を付けると `.husky/pre-commit` ・ `.husky/commit-msg` も配置
|
|
139
86
|
|
|
140
|
-
|
|
87
|
+
### Codex CLI を使う場合
|
|
141
88
|
|
|
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
|
-
}
|
|
89
|
+
```bash
|
|
90
|
+
npx phasegate init --name my-project --agent codex --with-husky
|
|
91
|
+
codex features enable codex_hooks # Codex 本体の feature flag を手動で有効化
|
|
167
92
|
```
|
|
168
93
|
|
|
169
|
-
|
|
94
|
+
両方使う場合は `--agent both`。詳細は [Codex Integration Guide](docs/guide/codex-integration.md) を参照。
|
|
170
95
|
|
|
171
|
-
###
|
|
172
|
-
|
|
173
|
-
L4 は CI の cron スケジュールで週次実行します。`consistency-check` テンプレートを使います:
|
|
96
|
+
### アップデート
|
|
174
97
|
|
|
175
98
|
```bash
|
|
176
|
-
|
|
177
|
-
npx phasegate
|
|
99
|
+
npm update phasegate
|
|
100
|
+
npx phasegate update-skills # スキルを最新版に再デプロイ
|
|
178
101
|
```
|
|
179
102
|
|
|
180
|
-
|
|
103
|
+
---
|
|
181
104
|
|
|
182
|
-
|
|
105
|
+
## 主な機能
|
|
183
106
|
|
|
184
|
-
|
|
107
|
+
| 機能 | できること |
|
|
108
|
+
|---|---|
|
|
109
|
+
| **フェーズゲート** | 設計文書がないと実装ファイルへの Write/Edit/Bash をブロック。AIDLC 準拠 / カスタム gate の両方をサポート |
|
|
110
|
+
| **5 層バリデーション (L0-L4)** | エディタ保存 → pre-commit → CI → 週次まで段階的に品質チェック |
|
|
111
|
+
| **28 AIDLC スキル** | 要求定義 → ドメイン設計 → テスト設計 → TDD 実装をスキルとして提供 |
|
|
112
|
+
| **Quick Mode** | バグ修正・docs・テスト追加など軽微変更ではゲートを緩和して高速化 |
|
|
113
|
+
| **Claude Code / Codex Hooks** | Write/Edit/Bash 時に自動でゲートチェック・lint を実行 |
|
|
114
|
+
| **HarnessError 形式** | 全エラーに ADR 参照 + 修正例が含まれ、AI が自己修正できる |
|
|
115
|
+
| **Baseline (retrofit)** | 既存リポジトリ導入時、`baseline` snapshot に登録した既存ファイルは構造的に編集されるまで gate 対象外 |
|
|
185
116
|
|
|
186
117
|
---
|
|
187
118
|
|
|
188
|
-
##
|
|
189
|
-
|
|
190
|
-
プロジェクトルートに配置する品質設定の Single Source of Truth です。
|
|
119
|
+
## 5 層防御モデル
|
|
191
120
|
|
|
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
|
-
}
|
|
121
|
+
```
|
|
122
|
+
+------------------------------------------------------------------+
|
|
123
|
+
| L0 AI agent runtime + git hooks |
|
|
124
|
+
| PreToolUse / PostToolUse / Stop / SessionStart / |
|
|
125
|
+
| UserPromptSubmit + .husky/pre-commit + .husky/commit-msg |
|
|
126
|
+
+------------------------------------------------------------------+
|
|
127
|
+
| L1 エディタ時 / `phasegate lint` |
|
|
128
|
+
| @unit / @layer メタデータ, レイヤー違反, AI アンチパターン |
|
|
129
|
+
+------------------------------------------------------------------+
|
|
130
|
+
| L2 pre-commit |
|
|
131
|
+
| phase-gate, story-reflection, テスト品質 (AAA/日本語名) |
|
|
132
|
+
+------------------------------------------------------------------+
|
|
133
|
+
| L3 CI/CD |
|
|
134
|
+
| security, performance, coverage 90%/95%, 要件カバレッジ |
|
|
135
|
+
+------------------------------------------------------------------+
|
|
136
|
+
| L4 週次 (default off) |
|
|
137
|
+
| 設計-コード乖離, 文書整合性, デッドコード, 文書鮮度 |
|
|
138
|
+
+------------------------------------------------------------------+
|
|
224
139
|
```
|
|
225
140
|
|
|
226
|
-
|
|
227
|
-
|
|
228
|
-
|
|
229
|
-
|
|
230
|
-
|
|
231
|
-
|
|
232
|
-
|
|
|
233
|
-
|---|---|---|---|
|
|
234
|
-
| **minimal** | L1, L2 | -- | プロトタイプ・学習 |
|
|
235
|
-
| **standard** | L1-L3 | 90% | 通常開発（デフォルト） |
|
|
236
|
-
| **strict** | L1-L4 | 95% | 本番・エンタープライズ |
|
|
237
|
-
|
|
238
|
-
### layers.L1.rules -- AST ルール設定
|
|
141
|
+
| Layer | 実行タイミング | コマンド |
|
|
142
|
+
|---|---|---|
|
|
143
|
+
| **L0** | AI agent / git hook | runtime 自動（`.claude/settings.json` 等） |
|
|
144
|
+
| **L1** | 保存時 | `npx phasegate lint` |
|
|
145
|
+
| **L2** | コミット前 | `npx phasegate validate --layer L2` |
|
|
146
|
+
| **L3** | CI/CD | `npx phasegate validate --layer L3` |
|
|
147
|
+
| **L4** | 週次 cron | `npx phasegate validate --layer L4` |
|
|
239
148
|
|
|
240
|
-
|
|
149
|
+
エラーは `HarnessError` 形式（理由 / ADR 参照 / 修正例）で返されるため、AI agent が自己修正できます。
|
|
241
150
|
|
|
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
|
-
```
|
|
151
|
+
> `--layer L0` の `L0-001` / `L0-002` は legacy validator で `enabled: false`。実体の L0 は agent-integration の hook と Husky です。
|
|
255
152
|
|
|
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` 必須） |
|
|
153
|
+
詳細: [5-Layer Defense Model](docs/guide/layer-model.md)
|
|
279
154
|
|
|
280
|
-
|
|
155
|
+
---
|
|
281
156
|
|
|
282
|
-
|
|
157
|
+
## 28 AIDLC スキル
|
|
283
158
|
|
|
284
|
-
|
|
159
|
+
AIDLC (AI-Driven Development Life Cycle) は **要求定義 → 設計 → テスト設計 → TDD 実装** の順序を強制するプロセスです。各スキルは前のレベルの成果物を入力にします。
|
|
285
160
|
|
|
286
|
-
|
|
161
|
+
**最初の一歩**: Claude Code / Codex 内で `/product-architect` を実行。
|
|
287
162
|
|
|
288
|
-
|
|
289
|
-
2. 検出した各 US について、inception 側のファイルが存在するかチェック
|
|
290
|
-
3. 存在する場合、対応する product 側のファイルに `@story-id` アノテーションが含まれるかチェック
|
|
291
|
-
4. **含まれていなければ書き込みをブロック**
|
|
163
|
+
### 5 グループ（28 スキル）
|
|
292
164
|
|
|
293
|
-
|
|
294
|
-
|
|
295
|
-
|
|
296
|
-
|
|
297
|
-
|
|
165
|
+
| グループ | スキル |
|
|
166
|
+
|---|---|
|
|
167
|
+
| **Foundation (4)** | `/product-architect` `/story-writer` `/story-mapper` `/unit-designer` |
|
|
168
|
+
| **Design (5)** | `/domain-designer` `/logical-designer` `/mock-designer` `/uiux-designer` `/environment-designer` |
|
|
169
|
+
| **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` |
|
|
170
|
+
| **Implementation (4)** | `/story-implementor` `/quick-implementor` `/implementation-planner` `/implementation-readiness-checker` |
|
|
171
|
+
| **Verification (8)** | `/consistency-checker` `/cascade-updater` `/codex-delegator` `/codebase-mapper` `/doc-freshness-checker` `/pointer-validator` `/engineering-perspective` `/skill-creator` |
|
|
298
172
|
|
|
299
|
-
|
|
173
|
+
各スキルの詳細・成果物・前提条件: [Skills Overview](docs/guide/skills-overview.md)
|
|
300
174
|
|
|
301
|
-
|
|
175
|
+
---
|
|
302
176
|
|
|
303
|
-
|
|
304
|
-
<!-- docs/product/construction/my-unit/logical_design.md -->
|
|
177
|
+
## メタデータ規約
|
|
305
178
|
|
|
306
|
-
|
|
179
|
+
ソースファイル先頭に `@unit` / `@layer` を、テストには `@story` を記載します。L1 はこれを使ってレイヤー違反検出と drift-detection を行います。
|
|
307
180
|
|
|
308
|
-
|
|
309
|
-
|
|
310
|
-
|
|
181
|
+
```typescript
|
|
182
|
+
// @unit config-foundation
|
|
183
|
+
// @layer domain
|
|
184
|
+
// @story US-001 ← テストファイルのみ
|
|
311
185
|
|
|
312
|
-
|
|
313
|
-
### OrderRepository Port
|
|
314
|
-
- findByUserId(id: UserId): Promise<Order[]>
|
|
186
|
+
export class ConfigSchema { ... }
|
|
315
187
|
```
|
|
316
188
|
|
|
317
|
-
|
|
189
|
+
| タグ | 値 |
|
|
190
|
+
|---|---|
|
|
191
|
+
| `@unit` | `/unit-designer` が定義した Unit 名（例: `config-foundation`） |
|
|
192
|
+
| `@layer` | `architecture.preset` で定義した層名（例: `domain` / `application` / `infrastructure` / `presentation`） |
|
|
193
|
+
| `@story` | 検証する US の ID（例: `US-001`） |
|
|
318
194
|
|
|
319
|
-
|
|
195
|
+
---
|
|
320
196
|
|
|
321
|
-
|
|
322
|
-
|---|---|---|
|
|
323
|
-
| `docs/inception/{unit}/{storyId}/logical_design.md` | `docs/product/construction/{unit}/logical_design.md` | **Yes**（ブロック） |
|
|
324
|
-
| `docs/inception/{unit}/{storyId}/domain_model.md` | `docs/product/construction/{unit}/domain_model.md` | No（警告のみ） |
|
|
197
|
+
## 設定の要点
|
|
325
198
|
|
|
326
|
-
|
|
199
|
+
`phasegate.config.json` が品質設定の Single Source of Truth です。**ほぼ全項目にデフォルトがあるため、まずは init が生成したものをそのまま使えば動きます**。
|
|
327
200
|
|
|
328
201
|
```jsonc
|
|
329
202
|
{
|
|
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
|
-
}
|
|
203
|
+
"project": { "name": "my-project", "preset": "standard" },
|
|
204
|
+
"architecture": { "preset": "clean" },
|
|
205
|
+
"layers": {
|
|
206
|
+
"L0": { "enabled": false }, "L1": { "enabled": true },
|
|
207
|
+
"L2": { "enabled": true }, "L3": { "enabled": true },
|
|
208
|
+
"L4": { "enabled": false }
|
|
209
|
+
},
|
|
210
|
+
"phaseDependencies": { "preset": "standard", "storyReflection": { "enabled": true } },
|
|
211
|
+
"quickMode": { "allowedCategories": ["bugfix", "docs", "test", "config"] },
|
|
212
|
+
"protectedFiles": { "exclude": ["package.json"] },
|
|
213
|
+
"baseline": { "enabled": true, "path": ".phasegate/baseline.json" }
|
|
348
214
|
}
|
|
349
215
|
```
|
|
350
216
|
|
|
351
|
-
|
|
352
|
-
|
|
353
|
-
- **特定の US だけゲートを通すことはできません** — inception に存在する全 US の反映が必要です
|
|
354
|
-
- `/story-implementor --story US-001` の `--story` 引数はゲートに接続されていません。検出はファイルシステムの走査のみで行われます
|
|
355
|
-
|
|
356
|
-
### quickMode -- 軽微な変更の緩和
|
|
357
|
-
|
|
358
|
-
Quick Mode は以下の方法で発動します:
|
|
359
|
-
|
|
360
|
-
- **CLI**: `npx phasegate ci-check --quick`
|
|
361
|
-
- **スキル**: `/quick-implementor` を使用すると自動で Quick Mode が適用されます
|
|
362
|
-
|
|
363
|
-
`bugfix`, `docs`, `test`, `config` カテゴリの変更では、Phase Gate と 2-Phase Execution を緩和し L1/L2 のみ維持します。
|
|
217
|
+
### 3 系統の preset（呼称分離）
|
|
364
218
|
|
|
365
|
-
|
|
219
|
+
phasegate には独立した 3 系統の preset があります。役割が違うので呼び分けます。
|
|
366
220
|
|
|
367
|
-
|
|
|
368
|
-
|
|
369
|
-
|
|
|
370
|
-
| `
|
|
371
|
-
|
|
|
221
|
+
| 呼称 | 設定キー | 値 | 役割 |
|
|
222
|
+
|---|---|---|---|
|
|
223
|
+
| **防御プリセット** | `project.preset` | `minimal` / `standard` / `strict` | 有効レイヤーとカバレッジ閾値を決める |
|
|
224
|
+
| **アーキプリセット** | `architecture.preset` | `clean` / `strict-ddd` / `onion` / `hexagonal` / `layered` / `flat` / `custom` | L1 が検査する層構造と依存方向 |
|
|
225
|
+
| **フェーズプリセット** | `phaseDependencies.preset` | `full` / `standard` / `minimal` / `custom` | フェーズゲートの厳密度 |
|
|
372
226
|
|
|
373
|
-
|
|
227
|
+
`npx phasegate init --preset <id>` の `--preset` は **フェーズプリセット**（`full / standard / minimal / custom`）を設定します。`project.preset` の `strict` は別概念です。
|
|
374
228
|
|
|
375
|
-
|
|
229
|
+
選定ガイド: [Preset Selection Guide](docs/guide/preset-selection.md)
|
|
376
230
|
|
|
377
|
-
|
|
231
|
+
### 主要キー
|
|
378
232
|
|
|
379
|
-
|
|
|
233
|
+
| キー | 効果 |
|
|
380
234
|
|---|---|
|
|
381
|
-
| `
|
|
382
|
-
| `package
|
|
383
|
-
| `
|
|
384
|
-
| `
|
|
235
|
+
| `quickMode.fullModeRequiredWhen` | Quick Mode → Full Mode への強制エスカレート条件（複数カテゴリ混在 / 新規ドメインファイル / API 契約変更）。安全側の default は全 `true` |
|
|
236
|
+
| `protectedFiles.exclude` | デフォルト保護対象（`package.json`, `tsconfig.json`, `biome.json` 等）から除外したいファイル |
|
|
237
|
+
| `baseline.enabled` | 既存リポジトリ導入時の retrofit grandfather。default `true`。`npx phasegate baseline` で snapshot 生成 |
|
|
238
|
+
| `phaseDependencies.storyReflection` | inception 設計が product docs に反映されるまで `src/{unit}/` への書き込みをブロック |
|
|
385
239
|
|
|
386
|
-
|
|
240
|
+
詳細: [Configuration Guide](docs/guide/configuration.md)
|
|
387
241
|
|
|
388
242
|
---
|
|
389
243
|
|
|
390
|
-
## CLI
|
|
244
|
+
## CLI 主要コマンド
|
|
391
245
|
|
|
392
246
|
```bash
|
|
393
247
|
npx phasegate <command> [options]
|
|
394
248
|
```
|
|
395
249
|
|
|
396
|
-
### セットアップ
|
|
397
|
-
|
|
398
250
|
| コマンド | 説明 |
|
|
399
251
|
|---|---|
|
|
400
|
-
| `init --name <name>` |
|
|
252
|
+
| `init --name <name>` | 初期化（skills/config/hooks 配置）。`--agent claude\|codex\|both`、`--with-husky`、`--preset <full\|standard\|minimal\|custom>` |
|
|
401
253
|
| `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
|
-
|---|---|
|
|
254
|
+
| `lint` | L1 Biome AST チェック |
|
|
255
|
+
| `validate --layer <L1\|L2\|L3\|L4\|all>` | 指定レイヤーのバリデータ実行（`--format human\|agent\|ci`） |
|
|
256
|
+
| `ci-check` | CI フルチェック（L2-L4）。`--quick` で Quick Mode |
|
|
257
|
+
| `check-change-category --paths <csv>` | 変更ファイルを Quick Mode カテゴリに分類、Full Mode 強制が必要かを返す |
|
|
258
|
+
| `baseline` | retrofit grandfather snapshot 生成（`--dry-run`, `--force`, `--paths <glob>`, `--json`） |
|
|
259
|
+
| `scaffold-design --unit <id> --phase <logical\|domain\|uiux\|unit-test\|it-test>` | 最小構成の設計文書を `templates/` から生成 |
|
|
435
260
|
| `phasegate:status` | 全体の健全性サマリ |
|
|
436
|
-
| `phasegate:check-ready` | 全 story の Phase Gate 通過状態 |
|
|
437
261
|
| `phasegate:check-phase --unit <id>` | 指定 Unit の現在フェーズ |
|
|
438
|
-
| `phasegate:ci-check` | 全 L3 バリデータ実行 |
|
|
439
262
|
| `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` キーを追加、既存設定は保持）。冪等。 |
|
|
263
|
+
| `migrate work-items --dry-run` / `--apply` | 旧 `ISSUE-XXX` / `H{NN}-{NN}` を `WI-XXX` 統一レイアウトへ移行 |
|
|
264
|
+
| `migrate --schema v3` | `phasegate.config.json` を v3 schema へ昇格（`architecture` キー追加） |
|
|
265
|
+
| `ci:generate-template --type <aidlc-gate\|pre-commit\|consistency-check>` | CI/CD テンプレート生成（`--render` でファイル出力） |
|
|
266
|
+
| `list-errors --layer <L0-L4>` | エラー定義一覧 |
|
|
267
|
+
| `hook <pre-tool-use\|post-tool-use\|stop>` | agent hook を起動（stdin から JSON） |
|
|
268
|
+
| `pre-commit` | L2 pre-commit バリデータをステージファイルに適用 |
|
|
454
269
|
|
|
455
|
-
|
|
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） |
|
|
462
|
-
|
|
463
|
-
> 開発者向けコマンド（回帰テスト、Hooks Engine、Phase 2 拡張、スキル品質）は [DEVELOPMENT.ja.md](DEVELOPMENT.ja.md) を参照してください。
|
|
270
|
+
完全な CLI Reference: [CLI Reference](docs/guide/cli-reference.md)
|
|
464
271
|
|
|
465
272
|
---
|
|
466
273
|
|
|
467
|
-
##
|
|
468
|
-
|
|
469
|
-
AIDLC (AI-Driven Development Life Cycle) は設計 → テスト設計 → TDD 実装の順序を強制するプロセスです。各レベルの成果物が次のレベルの前提条件になります。
|
|
470
|
-
|
|
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 にグルーピング |
|
|
274
|
+
## Hooks 統合
|
|
491
275
|
|
|
492
|
-
###
|
|
276
|
+
### Claude Code
|
|
493
277
|
|
|
494
|
-
|
|
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 実装ロジック設計 |
|
|
506
|
-
|
|
507
|
-
### Level 3: ストーリー実装（成果物: `docs/inception/{unit}/{US-XXX}/`）
|
|
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
|
-
| タグ | 値の決め方 | 例 |
|
|
551
|
-
|---|---|---|
|
|
552
|
-
| `@unit` | `/unit-designer` スキルが定義した Unit 名を使用。手動の場合はドメインの論理グループ名 | `config-foundation`, `validator-system` |
|
|
553
|
-
| `@layer` | ファイルの役割に応じて4値から選択 | `domain` / `application` / `infrastructure` / `presentation` |
|
|
554
|
-
| `@story` | テストが検証するユーザーストーリーの ID | `US-001`, `US-003` |
|
|
555
|
-
|
|
556
|
-
これにより L1 検証（`require-unit-comment`, `require-layer-comment`）・トレーサビリティ・drift-detection が機能します。タグが欠けているファイルは L1 でエラーになります（`layers.L1.rules` で緩和可能）。
|
|
557
|
-
|
|
558
|
-
---
|
|
559
|
-
|
|
560
|
-
## Claude Code Hooks
|
|
561
|
-
|
|
562
|
-
`.claude/settings.json` に以下を設定すると、ファイル書き込み時に自動でゲートチェックと lint が実行されます。
|
|
563
|
-
|
|
564
|
-
```jsonc
|
|
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
|
-
```
|
|
278
|
+
`init` が `.claude/settings.json` に以下を配置します。
|
|
597
279
|
|
|
598
280
|
| Hook | タイミング | 動作 |
|
|
599
281
|
|---|---|---|
|
|
600
|
-
| **PreToolUse** | Write/Edit/Bash
|
|
601
|
-
| **PostToolUse** | Write/Edit
|
|
602
|
-
| **Stop** | セッション終了前 | L2-L4
|
|
603
|
-
|
|
604
|
-
ブロック時は違反理由・不足している設計文書・次に実行すべきスキルを含むエラーメッセージが返されます。
|
|
605
|
-
|
|
606
|
-
> **オプション**: `.claude/scripts/` 配下にシェルスクリプトフック（deny-check, format, analyze-errors 等）を追加配置できます。詳細は [DEVELOPMENT.ja.md](DEVELOPMENT.ja.md#オプション-シェルスクリプトフック) を参照してください。
|
|
607
|
-
|
|
608
|
-
---
|
|
609
|
-
|
|
610
|
-
## Codex CLI Integration
|
|
282
|
+
| **PreToolUse** | Write/Edit/Bash の実行前 | フェーズゲート違反 / 保護ファイル / Bash 経由迂回をブロック。Quick→Full 強制条件のチェックも実行 |
|
|
283
|
+
| **PostToolUse** | Write/Edit の実行後 | Biome AST ルールを自動実行、違反を即時フィードバック |
|
|
284
|
+
| **Stop** | セッション終了前 | L2-L4 全チェックを実行、グリーンでないと終了を保留 |
|
|
611
285
|
|
|
612
|
-
|
|
286
|
+
### Codex CLI
|
|
613
287
|
|
|
614
|
-
|
|
615
|
-
|
|
616
|
-
```bash
|
|
617
|
-
# 1. Codex 向けにプロジェクトを初期化（.codex/hooks.json や .codex/skills など project 内ファイルを作成）
|
|
618
|
-
npx phasegate init --name my-project --agent codex --with-husky
|
|
619
|
-
|
|
620
|
-
# 2. Codex CLI 側の feature flag を手動で有効化
|
|
621
|
-
codex features enable codex_hooks
|
|
622
|
-
```
|
|
623
|
-
|
|
624
|
-
Claude + Codex 両対応プロジェクトは `--agent both` を指定してください。
|
|
625
|
-
|
|
626
|
-
`init` が担当するのは project 内のセットアップです。`codex_hooks` の有効化は Codex 本体のユーザー設定なので、明示的に手動実行します。
|
|
627
|
-
|
|
628
|
-
### カバレッジと既知の制約
|
|
629
|
-
|
|
630
|
-
Codex のネイティブ `apply_patch` ツールは内部の `ApplyPatchHandler` 経由で実行され hook を発火しません（[openai/codex#16732](https://github.com/openai/codex/issues/16732)）。このため pre-edit hard block は Bash 経由の書き込みに限定され、ネイティブ `apply_patch` の違反は **pre-commit (L2)** で commit 時にブロックされます。
|
|
288
|
+
`init --agent codex` で `.codex/hooks.json` を配置。Codex のネイティブ `apply_patch` ツールは hook を発火しないため（[openai/codex#16732](https://github.com/openai/codex/issues/16732)）、ネイティブ経路は **pre-commit (L2)** で commit 時にブロックされます。
|
|
631
289
|
|
|
632
290
|
| 編集経路 | 事前 hard block | commit 時 block |
|
|
633
291
|
|---|---|---|
|
|
634
|
-
| Bash 書き込み（`sed -i`, `tee`, heredoc, `cat >`） | ✅
|
|
635
|
-
| Bash 経由 `apply_patch <<'PATCH'` | ✅
|
|
636
|
-
| Codex ネイティブ `apply_patch`
|
|
292
|
+
| Bash 書き込み（`sed -i`, `tee`, heredoc, `cat >`） | ✅ PreToolUse(Bash) | ✅ pre-commit |
|
|
293
|
+
| Bash 経由 `apply_patch <<'PATCH'` | ✅ PreToolUse(Bash) | ✅ pre-commit |
|
|
294
|
+
| Codex ネイティブ `apply_patch` | ❌ Codex 側の制約で hook 非発火 | ✅ pre-commit |
|
|
637
295
|
|
|
638
|
-
**推奨運用**: こまめに commit
|
|
639
|
-
|
|
640
|
-
---
|
|
296
|
+
**推奨運用**: こまめに commit して pre-commit でネイティブ `apply_patch` 違反を早期に surface する。
|
|
641
297
|
|
|
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
|
-
```
|
|
746
|
-
|
|
747
|
-
この設定では以下の順序が強制されます:
|
|
748
|
-
|
|
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
|
-
```
|
|
757
|
-
|
|
758
|
-
> **ヒント**: `standard` や `full` プリセットはこのフローの大部分をゼロコンフィグで適用します。カスタムゲートは、段階をより細かく制御したい場合や AIDLC 以外のワークフローに使います。
|
|
759
|
-
|
|
760
|
-
---
|
|
761
|
-
|
|
762
|
-
## CI/CD テンプレート
|
|
763
|
-
|
|
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
|
-
```
|
|
769
|
-
|
|
770
|
-
`--render` オプションでファイルに直接出力できます:
|
|
771
|
-
|
|
772
|
-
```bash
|
|
773
|
-
npx phasegate ci:generate-template --type aidlc-gate --render > .github/workflows/aidlc-gate.yml
|
|
774
|
-
```
|
|
775
|
-
|
|
776
|
-
> **既知の問題**: `--preset` オプションでデフォルトプリセットが見つからないエラーが発生する場合があります。`--preset` を省略して実行してください。
|
|
298
|
+
詳細: [Hooks Integration](docs/guide/hooks-integration.md) ・ [Codex Integration](docs/guide/codex-integration.md)
|
|
777
299
|
|
|
778
300
|
---
|
|
779
301
|
|
|
@@ -781,62 +303,68 @@ npx phasegate ci:generate-template --type aidlc-gate --render > .github/workflow
|
|
|
781
303
|
|
|
782
304
|
```
|
|
783
305
|
your-project/
|
|
784
|
-
├── phasegate.config.json
|
|
306
|
+
├── phasegate.config.json
|
|
785
307
|
├── docs/
|
|
786
308
|
│ ├── folder_management_rules.md
|
|
787
|
-
│ ├── principles/
|
|
788
|
-
│ ├── product/
|
|
789
|
-
│
|
|
790
|
-
│ │ ├── units/{unit}.md
|
|
791
|
-
│ │ └── construction/{unit}/
|
|
792
|
-
│ │ ├── domain_model.md
|
|
793
|
-
│ │ └── logical_design.md
|
|
794
|
-
│ ├── inception/ # AIDLC が生成する設計計画文書
|
|
795
|
-
│ │ ├── _shared/ # Level 1（プロダクト全体）
|
|
796
|
-
│ │ └── {unit}/{US-XXX}/ # Level 2/3（Unit・ストーリー単位）
|
|
309
|
+
│ ├── principles/ # アーキテクチャ哲学・テスト規約
|
|
310
|
+
│ ├── product/construction/{unit}/ # 確定版設計（domain_model.md / logical_design.md）
|
|
311
|
+
│ ├── inception/{unit}/{US-XXX}/ # AIDLC が生成する設計計画
|
|
797
312
|
│ └── ADR/
|
|
798
|
-
├── src/
|
|
799
|
-
├── .claude/
|
|
800
|
-
|
|
801
|
-
|
|
802
|
-
├── .codex/
|
|
803
|
-
│ ├── hooks.json # Codex hooks 設定
|
|
804
|
-
│ └── skills/ # ../skills への symlink（Codex有効時）
|
|
805
|
-
└── skills/ # npx phasegate init で再生成可能
|
|
313
|
+
├── src/ # 実装コード（@unit/@layer 必須）
|
|
314
|
+
├── .claude/{settings.json, skills/}
|
|
315
|
+
├── .codex/{hooks.json, skills/}
|
|
316
|
+
└── skills/ # init で再生成可能
|
|
806
317
|
```
|
|
807
318
|
|
|
808
|
-
|
|
319
|
+
推奨 `.gitignore`:
|
|
809
320
|
|
|
810
321
|
```
|
|
811
322
|
node_modules/
|
|
812
|
-
skills/ #
|
|
813
|
-
.claude/skills/ #
|
|
814
|
-
.codex/skills/ #
|
|
323
|
+
skills/ # init で再生成可能
|
|
324
|
+
.claude/skills/ # symlink
|
|
325
|
+
.codex/skills/ # symlink
|
|
815
326
|
dist/
|
|
816
327
|
reports/
|
|
817
328
|
```
|
|
818
329
|
|
|
819
330
|
---
|
|
820
331
|
|
|
821
|
-
##
|
|
332
|
+
## ロードマップ
|
|
822
333
|
|
|
823
|
-
|
|
334
|
+
ドキュメントで言及があるが現状 partial 実装または user 配線に依存しているもの。各 Work Item は `docs/inception/_cross/WI-XXX/description.md` に起票済み。
|
|
824
335
|
|
|
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`) の撤去 |
|
|
336
|
+
| Work Item | 内容 |
|
|
337
|
+
|---|---|
|
|
338
|
+
| **[WI-031](docs/inception/_cross/WI-031/description.md)** | CI template の二系統統一 + `phasegate init --with-ci` |
|
|
339
|
+
| **[WI-032](docs/inception/_cross/WI-032/description.md)** | AGENTS.md / CLAUDE.md auto-refresh パイプライン |
|
|
340
|
+
| **[WI-033](docs/inception/_cross/WI-033/description.md)** | `doc-freshness` / `pointer-validation` を L4 validator に昇格 |
|
|
341
|
+
| **[WI-034](docs/inception/_cross/WI-034/description.md)** | L0 legacy validator (`L0-001` / `L0-002`) の撤去 |
|
|
342
|
+
|
|
343
|
+
L3 Nyquist Validation の `requirement-test-matrix.json` 自動生成パイプラインも未完成（手動セットアップで利用可）。
|
|
344
|
+
|
|
345
|
+
---
|
|
346
|
+
|
|
347
|
+
## ドキュメント
|
|
348
|
+
|
|
349
|
+
- [Installation](docs/guide/installation.md) — 詳細インストール手順
|
|
350
|
+
- [Configuration](docs/guide/configuration.md) — `phasegate.config.json` 完全リファレンス
|
|
351
|
+
- [CLI Reference](docs/guide/cli-reference.md) — 全 CLI コマンド・オプション
|
|
352
|
+
- [Skills Overview](docs/guide/skills-overview.md) — 28 スキルの実行順序と成果物
|
|
353
|
+
- [5-Layer Defense Model](docs/guide/layer-model.md) — L0-L4 詳細・HarnessError 形式
|
|
354
|
+
- [Hooks Integration](docs/guide/hooks-integration.md) — Claude Code Hooks 設定
|
|
355
|
+
- [Codex Integration](docs/guide/codex-integration.md) — Codex CLI セットアップ・カバレッジ
|
|
356
|
+
- [Quick Mode vs Full Mode](docs/guide/quick-vs-full-mode.md) — `/story-implementor` vs `/quick-implementor`
|
|
357
|
+
- [Retrofit Adoption Guide](docs/guide/retrofit-adoption.md) — 既存リポジトリへの段階的導入
|
|
358
|
+
- [Preset Selection Guide](docs/guide/preset-selection.md) — 3 系統の preset 選定
|
|
831
359
|
|
|
832
|
-
|
|
360
|
+
phasegate 自体の開発: [DEVELOPMENT.ja.md](DEVELOPMENT.ja.md)
|
|
833
361
|
|
|
834
362
|
---
|
|
835
363
|
|
|
836
|
-
##
|
|
364
|
+
## ライセンス
|
|
837
365
|
|
|
838
|
-
|
|
366
|
+
[MIT License](LICENSE)
|
|
839
367
|
|
|
840
368
|
---
|
|
841
369
|
|
|
842
|
-
*Last updated: 2026-04-25
|
|
370
|
+
*Last updated: 2026-04-25 — v0.110.0*
|