golem15/msd-core
3
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
9faacc0c153a88f939ef07ced74d56dc468f0708
msd-core/docs/ja-JP/reference/plan-md.md
Tom Boucher ffd5370464 fix(#2903): use the command form that actually works in reader-facing docs (#3047) 
* fix(#2903): use the command form that actually works in reader-facing docs

Docs told readers to type the colon form, which no runtime registers -- 18 of
19 runtimes use slash-hyphen and the 19th uses shell-var -- so anyone copying an
example got an unrecognized command. Swept 178 occurrences across 53 files,
locale mirrors included so they do not re-diverge from English.

The colon form is a source-authoring token, not a user-facing one: install-time
converters key on it to produce the hyphen form runtimes actually register. So
the sweep is scoped, and three things are deliberately left alone:

- ADRs, which are a historical record; editing their prose falsifies what was
  written at the time.
- The legacy release-notes archive, pending a maintainer decision on whether it
  follows the same historical carve-out. Excluding it keeps a later reversal
  additive rather than a revert.
- Source artifacts under commands, workflows and agents, where the colon form is
  load-bearing. Rewriting those would break the installed-skill guarantee across
  every runtime -- the single largest hazard here.

The plugin namespace form is a real, separate token and survives untouched.

Adds a lint enforcing exactly that boundary, since the correct form genuinely
differs by directory and nothing previously caught the drift.

Also fixes a hardcoded colon form in the capability-matrix generator. The sweep
alone would have left the generated matrix disagreeing with the template that
produces it, so the fix is at the source and the output regenerated.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

* fix(#2903): stop the sweep misquoting source frontmatter

Adversarial review caught three lines where the sweep rewrote a citation of the
literal YAML name: key from a source command file. That key genuinely is the
colon form -- this change's own carve-out logic says source-authoring tokens keep
it -- so the docs ended up misquoting the real files. One of the three is an
acceptance-checklist assertion, which the sweep turned into a false statement.

Restored the three citations to match their sources verbatim, surgically: where a
line carried both a name: citation and a real reader-facing slash command, only
the citation reverted and the command stayed corrected.

The guard needed the same distinction, or it would have flagged the restoration
and reddened the build: a gsd:<cmd> token preceded by name: is a citation of a
source token and is now permitted. The exemption is deliberately narrow -- a bare
gsd:<cmd> anywhere else still fails -- with a test pinning that narrowness.

Also makes the detection case-insensitive. Review found /GSD:next slipped through
silently; no such casing exists in the tree today, so this closes a latent gap
rather than fixing a live one.

Swept the whole tree for further corrupted citations: none beyond the three.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

* fix(#2903): retire the stale-next invariant and sweep next like every other command

Maintainer decision on a genuine conflict between two contracts.

Invariant #3054 banned the literal /gsd-next from user-facing docs because it
named a retired workflow-advance command. But commands/gsd/next.md is a live
command -- the state-aware smart-entry launcher -- and this issue requires docs
to use the hyphen form every runtime actually registers. Both could not hold for
this one command, so docs had been sidestepping the ban by keeping the colon
form, which is exactly the defect this issue exists to remove.

FEATURES.md already recorded the reassignment: the hyphen form "is not the
retired workflow-advance command; it is reserved for the state-aware smart-entry
launcher. Workflow advancement remains under /gsd-progress --next." With that
reassignment the invariant's premise is obsolete and the guard now contradicts
the documented command form, so it is retired with a comment recording why
rather than deleted silently.

next is now swept like every other command, and the earlier exemption added to
the new guard is removed so nothing is special-cased.

Four citations of the literal name: frontmatter key stay in colon form, because
the source file really does carry name: gsd:next and a doc quoting it must
reproduce it verbatim. Two of those lines were reworded to say which side is the
frontmatter key and which is the slash command, since they previously conflated
the two.

Verified the retired scan would now genuinely fail against this tree -- the
conflict was real and resolved, not dodged.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

* chore(#2903): backfill changeset pr number

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 5 <noreply@anthropic.com>
2026-08-04 13:23:44 -04:00

250 lines
16 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# PLAN.md スキーマリファレンス
フェーズごとの `PLAN.md` は GSD Core の実行可能な作業単位です — エグゼキューターエージェントに何を構築し、正しく構築されたことをどのように検証するかを正確に伝える構造化ドキュメントです。このページではそのスキーマを説明します。[ドキュメントインデックス](../../README.md) も参照してください。
---
## 概要
プランはフェーズディレクトリ内の以下のパスに保存されます：
```
.planning/phases/<NN>-<slug>/<NN>-<PP>-PLAN.md
```
例: `.planning/phases/03-post-feed/03-02-PLAN.md`（フェーズ3、プラン2）。
プランは `gsd-planner` エージェント（`/gsd-plan-phase` によって起動）が生成し、`execute-phase` が使用します。通常、フェーズには1〜4つのプランが含まれます。フェーズ内のプランは実行ウェーブに割り当てられ、独立した作業が並行して実行されます。
---
## YAML フロントマター
すべての PLAN.md は `---` デリミタの間にある YAML フロントマターブロックで始まります。
### 注釈付きサンプル
```yaml
---
phase: 03-post-feed
plan: 02
type: execute
wave: 2
depends_on: ["03-01"]
files_modified:
- src/components/PostFeed.tsx
- src/components/PostCard.tsx
- src/app/feed/page.tsx
autonomous: true
requirements: ["FEED-01", "FEED-03"]
user_setup: []
must_haves:
truths:
- "User can scroll through posts from followed accounts"
- "Each post shows author avatar, name, timestamp, and content"
- "Empty state appears when no posts exist"
artifacts:
- path: "src/components/PostFeed.tsx"
provides: "Scrollable post list"
min_lines: 40
- path: "src/components/PostCard.tsx"
provides: "Individual post card"
exports: ["PostCard"]
key_links:
- from: "src/components/PostFeed.tsx"
to: "/api/feed"
via: "fetch in useEffect"
pattern: "fetch.*api/feed"
---
```
### フロントマターフィールドリファレンス
| フィールド | 必須 | 型 | 用途 |
|---|---|---|---|
| `phase` | はい | string | フェーズ識別子。例: `03-post-feed`。 |
| `plan` | はい | string | フェーズ内のプラン番号。例: `02`。 |
| `type` | はい | `execute` または `tdd` | 標準プランは `execute`; テスト駆動プラン（実装前にテストを書く）は `tdd`。 |
| `wave` | はい | integer | 実行ウェーブ。ウェーブ1のプランは並行実行されます（依存なし）。ウェーブ2以降のプランは前のウェーブのすべてのプランが完了するまで待機します。`gsd-planner` がプランニング時に事前計算します。 |
| `depends_on` | はい | プラン ID の配列 | このプランが待機する必要があるプランの一覧。空配列 = ウェーブ1。例: `["03-01"]` はこのプランがフェーズ3のプラン01の後に実行されることを意味します。 |
| `files_modified` | はい | パスの配列 | このプランが作成または変更するすべてのファイル。プランチェッカーが同一ウェーブのファイル競合を検出するため、および execute-phase がマージ追跡のために使用します。 |
| `autonomous` | はい | boolean | すべてのタスクが `auto` タイプの場合に `true`。プランに人間の操作が必要な `checkpoint:*` タスクが含まれる場合は `false`。 |
| `requirements` | はい | ID の配列 | このプランが対処する ROADMAP.md の要件 ID。すべてのフェーズ要件 ID は少なくとも1つのプランの `requirements` フィールドに登場する必要があります。空配列は BLOCKER です。 |
| `user_setup` | いいえ | オブジェクトの配列 | Claude が自動化できない外部サービスのセットアップ手順（アカウント作成、シークレット取得、ダッシュボード設定など）。存在する場合、execute-phase は開発者向けに `USER-SETUP.md` チェックリストを生成します。 |
| `must_haves` | はい | object | ゴール逆引き型の検証基準。以下を参照。 |
---
## `must_haves` フィールド
`must_haves` はフェーズゴールを達成するために観察可能に真でなければならないことを記録します。プランニング中に導出され、実行後に `gsd-verifier` エージェントによって検証されます。
### サブフィールド
| サブフィールド | 型 | 用途 |
|---|---|---|
| `truths` | 文字列の配列 | ユーザーの視点からの観察可能な動作。それぞれが検証可能でなければなりません。例: `"User can send a message"`（`"WebSocket library installed"` は不可）。 |
| `artifacts` | オブジェクトの配列 | 実質的な実装（スタブではなく）で存在しなければならないファイル。 |
| `artifacts[].path` | string | プロジェクトルートからの相対ファイルパス。 |
| `artifacts[].provides` | string | このファイルが提供する機能。 |
| `artifacts[].min_lines` | integer（オプション） | スタブではないとみなす最小行数。 |
| `artifacts[].exports` | 文字列の配列（オプション） | 検証すべき期待される名前付きエクスポート。 |
| `artifacts[].contains` | string（オプション） | ファイルに存在しなければならない正規表現またはリテラルパターン。 |
| `key_links` | オブジェクトの配列 | アーティファクト間の重要な接続 — システムをエンドツーエンドで機能させる配線。 |
| `key_links[].from` | string | ソースファイルまたはコンポーネント。 |
| `key_links[].to` | string | ターゲットファイル、エンドポイント、またはモジュール。 |
| `key_links[].via` | string | 接続方法の説明（例: `fetch in useEffect`、`Prisma query`、`import`）。 |
| `key_links[].pattern` | string（オプション） | ソース内に接続が存在することを検証する正規表現。 |
---
## 本文構造
フロントマターの後、プラン本文はエグゼキューターエージェントが読み取る名前付き XML スタイルブロックを使用します。
### `<objective>`
プランが提供するものとプロジェクトにとっての重要性を述べます：
```xml
<objective>
Implement the post feed as a scrollable card list.
Purpose: Core display feature for the social feed phase.
Output: PostFeed and PostCard components wired to /api/feed.
</objective>
```
### `<execution_context>`
エグゼキューターが開始前に読むワークフローファイルの一覧。常に execute-plan ワークフローを含み、プランにチェックポイントタスクがある場合はチェックポイントリファレンスを追加します：
```xml
<execution_context>
@~/.claude/gsd-core/workflows/execute-plan.md
@~/.claude/gsd-core/templates/summary.md
</execution_context>
```
### `<context>`
エグゼキューターが読む必要があるソースファイルの参照。プロジェクトレベルのプランニングドキュメントと、プランが複製しなければならないパターンや型を持つすべてのソースファイルを含みます。同じフェーズの以前のプランの `SUMMARY.md` は、型や共有された意思決定への真の依存がある場合のみ含めます — 反射的には含めません：
```xml
<context>
@.planning/PROJECT.md
@.planning/ROADMAP.md
@.planning/STATE.md
@src/components/UserCard.tsx
</context>
```
### `<tasks>`
1つ以上の `<task>` 要素を含みます。`type="auto"` タスクのすべてのタスク要素には `<name>`、`<files>`、`<read_first>`、`<action>`、`<verify>`、`<acceptance_criteria>`、`<done>` が必要です。
---
## タスクタイプ
| タイプ | 用途 | 自律性 |
|---|---|---|
| `auto` | エグゼキューターが独立して実行できるすべて。 | 完全自律。 |
| `checkpoint:human-verify` | 人間が実行中の UI やサービスを確認する必要があるビジュアルまたは機能的な検証。 | 実行を一時停止して開発者に提示; 承認後に再開。 |
| `checkpoint:decision` | 実行中に浮上し開発者の入力が必要な実装上の選択。 | 実行を一時停止してオプションを提示; 選択後に再開。 |
| `checkpoint:human-action` | 真に避けられない手動ステップ（アカウント作成、ハードウェア操作）。控えめに使用。 | 実行を一時停止して確認後に再開。 |
チェックポイントタスクが含まれるプランはフロントマターに `autonomous: false` を設定する必要があります。
---
## `auto` タスク構造
```xml
<task type="auto">
<name>Task 1: Create PostCard component</name>
<files>src/components/PostCard.tsx</files>
<read_first>src/components/UserCard.tsx, src/types/post.ts</read_first>
<action>Create PostCard component accepting a Post prop (id, authorId, content, createdAt,
reactionCount). Render author avatar using UserAvatar from UserCard pattern. Show timestamp
using date-fns formatDistanceToNow. Export as named export PostCard.</action>
<verify>npx tsc --noEmit</verify>
<acceptance_criteria>
- src/components/PostCard.tsx exports named export PostCard
- PostCard.tsx contains "reactionCount" prop usage
- npx tsc --noEmit exits 0
</acceptance_criteria>
<done>PostCard renders post content with author and timestamp</done>
</task>
```
### `auto` タスクの必須フィールド
| フィールド | ルール |
|---|---|
| `<files>` | タスクが作成または変更するすべてのファイル。エグゼキューターはこれらのファイルのみを書き込みます。 |
| `<read_first>` | エグゼキューターが何かに触れる前に読まなければならないファイル — 変更するファイル、信頼できる参照パターンファイル、型や規則を複製しなければならないすべてのファイル。 |
| `<action>` | 正確な識別子、ファイルパス、関数シグネチャ、期待される値を含む具体的な指示。ターゲット状態を指定せずに「X を Y に合わせる」とは言いません。フェンスされたコードブロックや完全な実装を含みません。 |
| `<verify>` | タスクが成功したことを証明する実行可能なコマンドまたはチェック。合格と不合格を区別できなければなりません — `echo "done"` は無効です。 |
| `<acceptance_criteria>` | 検証可能な条件: grep で検証可能な文字列、コマンドの終了コード、観察可能な動作。主観的な言語（「正しく見える」、「適切に設定されている」）は使用しません。 |
| `<done>` | 完了した成果の短い測定可能な説明。 |
---
## プラン品質ディメンション
`gsd-plan-checker` エージェントは実行開始前に12のディメンションにわたってすべての PLAN.md をレビューします。BLOCKER 深刻度のチェックに失敗したプランは `gsd-planner` に差し戻されます（最大3回のイテレーション）：
| ディメンション | チェック内容 |
|---|---|
| **1 — Requirement Coverage** | ROADMAP.md からのすべてのフェーズ要件 ID が少なくとも1つのプランの `requirements` フロントマターフィールドに登場し、対応するタスクがある。 |
| **2 — Task Completeness** | すべての `auto` タスクが必須フィールド（`<files>`、`<action>`、`<verify>`、`<acceptance_criteria>`、`<done>`）を持つ。曖昧なフィールドや空のフィールドがない。 |
| **3 — Dependency Correctness** | `depends_on` の参照が有効で非循環かつウェーブ番号と整合している。ウェーブ N のプランはウェーブ < N のプランのみに依存する。 |
| **4 — Key Links Planned** | `must_haves.key_links` のアーティファクトに、アーティファクトの作成だけでなく配線を実装する対応するタスクがある。 |
| **5 — Scope Sanity** | プランはコンテキスト予算内に収まる: プランあたり2〜3タスク（4 = 警告、5以上 = BLOCKER）、プランあたり8〜10ファイル以下（15以上 = BLOCKER）。 |
| **6 — Verification Derivation** | `must_haves.truths` は実装の詳細ではなくユーザー観察可能な動作。アーティファクトが truths にマッピングされる。key links が重要な配線をカバーする。 |
| **7 — Context Compliance** | CONTEXT.md のすべての `D-NN` 決定が少なくとも1つのタスクによって対処されている。`<deferred>` にあるものをタスクが実装していない。 |
| **7b — Scope Reduction Detection** | タスクアクションが、完全な決定スコープを提供せずにロックされた決定を暗黙的に「v1」、「スタブ」、または「将来の強化」に縮小していない。発見された場合は常に BLOCKER。 |
| **7c — Architectural Tier Compliance** | タスクが RESEARCH.md の Architectural Responsibility Map（存在する場合）に従って正しいティアに機能を割り当てている。誤ったティアのセキュリティ機密機能は BLOCKER。 |
| **8 — Nyquist Compliance** | `workflow.nyquist_validation` が有効で RESEARCH.md が存在する場合、すべてのタスクに `<automated>` 検証コマンドがあり、連続する3タスクのウィンドウにカバレッジがなく、VALIDATION.md が存在する。 |
| **9 — Cross-Plan Data Contracts** | プランがデータパイプラインを共有する場合、それらの変換が互換性を持つ — 別のプランが元の形式で必要とするデータをプランが削除しない。 |
| **10 — CLAUDE.md Compliance** | プランが `./CLAUDE.md` のプロジェクト固有の規則、禁止パターン、必須ツール、セキュリティ要件を遵守している。 |
| **11 — Research Resolution** | RESEARCH.md が存在する場合、プランニングを進める前にその `## Open Questions` セクションが `(RESOLVED)` とマークされている。 |
| **12 — Pattern Compliance** | PATTERNS.md が存在する場合、タスクが新規または変更される各ファイルに対して正しいアナログパターンを参照している。 |
---
## ウェーブ実行モデル
ウェーブ番号はプランニング中に事前計算されます。Execute-phase はウェーブ番号でプランをグループ化し、各ウェーブのプランを並行して実行します：
```
Wave 1: Plan 01, Plan 02, Plan 03 (すべて同時実行 — 依存なし)
Wave 2: Plan 04 (Wave 1 完了を待機)
Wave 3: Plan 05 (Wave 2 完了を待機)
```
同一ウェーブ内で重複するファイルを変更するプランは同じウェーブに入れてはなりません — プランチェッカーのディメンション3がこれを BLOCKER としてフラグします。
---
## プラン出力
プランが正常に実行された後、エグゼキューターは以下のパスに SUMMARY.md を書き込みます：
```
.planning/phases/<NN>-<slug>/<NN>-<PP>-SUMMARY.md
```
SUMMARY.md は何が構築されたかの正規の記録です。同じフェーズの後続プランは、型や意思決定への真の依存がある場合にのみそれを参照できます。
---
## Related
- [CONTEXT.md スキーマ](context-md.md)
- [Planning artifacts](planning-artifacts.md)
- [Features](../../FEATURES.md)
- [docs index](../../README.md)
Reference in New Issue View Git Blame Copy Permalink