設計工程: 設計 PR と設計文書のタイトルが仕組みの語だけで、承認する人が目的を読めない → 目的（今の問題と直した後に成り立つこと）をタイトルと最初の章に置く規約を工程に入れる

[takemi-ohama]

何を見つけたか

設計工程（requirements-design → design → document-restructuring → pr → 承認の関門）を通った設計 Pull Request のタイトルと設計文書の H1 が、仕組みの語だけで書かれ、承認する人が「今どんな失敗が起きていて、マージすると何が変わるのか」を読めない。

2026-09-19、マイルストーン 13 の設計 PR 3 本が関門に揃った時点で、利用者から
「titleからして何を言ってるか分かりません。それぞれ目的を明らかにして全部書き直し」と指示を受けた。

PR	関門に出たタイトル	読めないもの
#781	Docs: 担当 1 回の起動の結末を共通の語彙で読む設計（#729 #619 #584）	「結末」「語彙」は本文を読んだ後にしか意味を持たない。利用上限で止まった担当が error で終わる、という現象が出ない
#782	Docs: 使える者の決定と席の埋め方を共通層へ移す設計（#727 #687 #478 #664 #648）	「席」「共通層」が何かは本文を読まないと分からない。担当が 1 者欠けると初期化が失敗する、という現象が出ない
#783	Docs: cross-review の「数えない」区分を棄却に限る設計（#732 #624 #706）	「区分」「棄却」は内部の分類名。修正の要る指摘を残したまま approved になる、という現象が出ない

設計・要求・契約の各文書も同じ形である。H1 は # #729 / #619 / #584: 結末の語彙を共通層で読み、起動し直しの可否を共通層が返す のように issue 番号の列 + 仕組みの語で、最初の段落は「要求は…にある。この文書は『どう作るか』だけを扱う」「この文書は既存の設計…を置き換える」という管理上の注記である。目的（何が壊れているか・誰が困るか・直すと何が成り立つか）は、要求文書の 7 項目の表の 1 行か、設計文書の「機能一覧」の後ろにしか現れない。

どこで見つけたか

/goal /ndf:development-workflow <マイルストーン 13> の 3 層の運転で、supervisor が設計の持ち場を通し、conductor が approval-request.md の形で提示物を組んで AskUserQuestion を出した時点。工程は全部通っている（cross-review 収束・pr-body-decisions.sh check 一致・必須の節の充足）のに、承認する人が判断に入れなかった。3 本とも書き直しになり、関門で止まった時間と書き直しの費用が掛かった。

直さないと何が起きるか

• 設計 PR が関門に届くたびに、承認する人が本文を最初から読むか、書き直しを指示することになる。関門の費用が設計の本数に比例して増える
• 3 層の運転では supervisor が人へ問えないため、タイトルの妥当性を誰も確かめずに関門へ届く。工程の側に規約が無いと、同じ形が毎回出る
• approval-request.md は「決めたこと」を決定の見出しのまま並べる。見出しが仕組みの語だと、提示物を読んでも判断できず、承認の提示物の設計（「要約で判断が変わるため見出しをそのまま並べる」）が効かない

修正レイヤー

設計工程の Skill と参照文書のうち、タイトル・H1・最初の章・決定の見出しの形を決めている（または決めていない）箇所。

場所	いまの形	何が足りないか
plugins/ndf/skills/design/references/design-template.md	H1 が # {課題番号}: {何を作るか}。最初の段落が「要求は…にある。この文書は『どう作るか』だけを扱う」	目的の章が無い。H1 の先頭が課題番号で、「何を作るか」は仕組みの語になりやすい
plugins/ndf/skills/design/references/decisions.md	### 決定 N: {結論を 1 文で}	結論だけで「何のために」が無い。見出しだけを並べる approval-request.md の提示物で意味を持たない
plugins/ndf/skills/requirements-design/SKILL.md	「6. 実装前に明文化する項目」の表の 1 行が「目的」	目的が表の 1 行で、文書の最初の章にもタイトルにも出ない
plugins/ndf/skills/pr/SKILL.md	「タイトル・説明は日本語」	タイトルの形を定めていない。設計 PR の接頭辞 design/ があっても、タイトルの中身は自由
plugins/ndf/skills/development-workflow/references/approval-request.md	タイトル「そのまま」、決めたこと「見出しをそのまま並べる」	元が読めない形なら提示物も読めない。提示物の先頭に「目的」の行が無い
plugins/ndf/skills/document-restructuring/SKILL.md	目安「結論・成果物が定義される位置 = 最初の章」	結論とタイトルの読み手（承認する人）が誰かを言っていない。タイトルは測っていない
plugins/ndf/skills/development-workflow/references/agent-layers.md	conductor → supervisor の指示の 8 項目	タイトルと目的の規約が指示に入らない

採る手

規約を 1 か所に置き、他は参照する（同じ規約を複数箇所へ書かない）。置き場所の候補は design/references/design-template.md（雛形が形を持つ）か markdown-writing（文書全般の書き方）で、設計工程だけでなく要求・PR 本文・提示物にも掛かるため、後者に置いて前者が参照する形が考えられる。決めるのは設計の工程で行う。

規約の中身（利用者の指示から起こしたもの。書き直しの実物は #781 #782 #783 の書き直し後のコミットにある）:

1. タイトル（PR と各文書の H1）は「<Skill 名>: <今起きている問題（利用者が見る現象）> → <直した後に成り立つこと>」の形。 仕組みの語（語彙・席・区分・共通層・契約）はタイトルに置かず本文へ。issue 番号は末尾の括弧へ
2. 各文書の最初の章は「目的」。 何が壊れているか・誰が困るか・直すと何が成り立つかを 5 行以内で書く。「既存の設計を置き換える」「要求は…にある」などの管理上の注記は目的の後か末尾の節へ寄せる
3. 決定の見出しは「何のために何を決めた」と読める語にする。 中身（結論・理由）の形は変えない
4. 承認の提示物は先頭に「目的」を置き、タイトルが 1 の形かを確かめてから提示する（pr-body-decisions.sh check と同じ位置の検査）
5. document-restructuring の測る指標に「タイトルから目的が読めるか（問題と結果の 2 要素が入っているか）」を足す
6. conductor → supervisor の起動の指示に 1〜3 を入れる

機械で見られるものは見る（タイトルに → または「〜ため」の形があるか、H1 の直後の章が「目的」か）。判断はレビューと承認する人が持つ。

完了条件

• 雛形・決定の書き方・要求・pr・提示物・再構成の 6 箇所が同じ規約を参照し、規約の本文は 1 か所にある
• development-workflow の 3 層の起動の指示に規約が入り、supervisor が書いた設計 PR のタイトルが関門で書き直しにならない
• 設計 PR の関門で、提示物の先頭に目的が 3 行以内で出る
• 既存の設計 PR 3 本（cross-review: 利用上限で止まった担当が「結果ファイル無し」と報告されて空振りの起動し直しで待たされ、止めた担当が後から結果を書く → 上限を理由に報告して同じラウンドで起動し直さず、止めた後は書かせない（#729 #619 #584） #781 cross-review / cross-refactoring: 参加する CLI が 1 者でも使えないと収束ループを開始できず、再開で渡した引数が黙って無視される → 使える者だけで開始し、cross-review は毎ラウンド 2 席を確保し、再開で渡した引数は反映されるか反映しないと知らされる（#727 #687 #478 #664 #648） #782 cross-review: 誤りを示されていない重大な指摘が数えられずに承認で終わる → 数えない指摘を棄却と軽微な指摘に限る（#732 #624 #706） #783）の書き直し後の形を、規約の実例として文書へ写す

由来

マイルストーン 13（#729 #727 #732 の設計 PR #781 #782 #783）の承認の関門。利用者の指示「メモリではなく、ndfの設計工程全体を改善するissueを投稿してください」による起票。

🤖 Generated with Claude Code