docs-new

name	docs-new
description	markshelf の docs/ に新しいドキュメント（要求定義 R / 要件定義 REQ / 仕様 SPEC / 用語集）を規約どおりの命名・配置・上向きリンク付きで追加する。ドキュメントを新規作成・分割したいときに使う。

docs-new — 規約に沿った新規ドキュメント作成

markshelf の docs/ は4階層（要求定義 → 要件定義 → 仕様 ＋ 用語集）で、命名・配置・リンク方向に厳格な規約がある。このスキルは新規ドキュメントをその規約どおりに作る。規約の根拠は docs/要求定義/README.md / docs/要件定義/README.md / docs/仕様/README.md。

手順

1. どのレイヤか確認する。 ユーザーの依頼から判断できなければ尋ねる:

   • 「ユーザー／ビジネスがこうありたい」→ 要求定義 (R)
   • 「システムが何をすべきか」→ 要件定義 (REQ)
   • 「どう実装するか」→ 仕様 (SPEC)
   • 横断的な単語の説明 → 用語集

2. 既存の番号体系を調べる。 同じレイヤのフォルダ一覧を見て、新しいテーマなら次のトップ番号（R5 の次は R6 等）、既存テーマの細分化なら次のサブ番号（REQ3.6 の次は REQ3.7 等）を決める。ls docs/{レイヤ} で確認すること。番号は飛ばさず連番にする。

3. 親レイヤの対応先を特定する。 REQ なら対応する R、SPEC なら対応する REQ を探す。無い場合はユーザーに確認し、必要なら先に上位ドキュメントを作る（上位が無い下位は宙に浮く）。用語集には親リンク不要。

4. ファイルを作成する。 下のテンプレートに従う。配置とファイル名:

   • 新テーマ（フォルダ＋親 README）: docs/{レイヤ}/{接頭辞}{n}-{テーマ}/README.md
   • 既存テーマの個別項目: docs/{レイヤ}/{接頭辞}{n}-{テーマ}/{接頭辞}{n}.{sub}-{名称}.md
   • 用語集: docs/用語集/{用語}.md

5. 検証する。 作成後に必ず docs-lint を実行し、error 0件を確認する:

   node .claude/skills/docs-lint/lint-docs.mjs
   

鉄則

• リンクは下位 → 上位の一方向のみ。 上位ドキュメントから下位へのリンクは絶対に張らない（リンクグラフが濁る）。
• 上向きリンクは本文の冒頭に置く。 REQ/SPEC の親フォルダ README だけでなく、個別の {接頭辞}{n}.{sub}-*.md にも必ず親リンクを張る。
• 相対パスの深さに注意。 {接頭辞}{n}.{sub}-*.md は {接頭辞}{n}-テーマ/ フォルダの中（docs から2階層）にあるので、親レイヤのフォルダまでは必ず ../../{親レイヤ}/…。../../../ は docs ルートを突き抜けてしまい、ビューアでは吸収されて動くが IDE・GitHub・実ファイルではリンク切れになるので使わないこと。

テンプレート

要求定義 — 新テーマ R{n}-{テーマ}/README.md

# R{n}: {テーマ}

{ユーザー／ビジネスが望む状態を1〜2文で}

## 背景

{何を解決したいか。なぜこの要求が要るのか}

※ 要求定義は最上位。下位レイヤへのリンクは張らない。

要求定義 — 個別 R{n}-{テーマ}/R{n}.{sub}-{名称}.md

# R{n}.{sub}: {名称}

{望む状態}

## 要求

- {満たしたい具体的な状態を箇条書き}

要件定義 — 新テーマ REQ{n}-{テーマ}/README.md

# REQ{n}: {テーマ}

[R{m} — {要求テーマ}](../../要求定義/R{m}-{要求テーマ}/README.md) を満たすため、{テーマ} の要件を定義する。

要件定義 — 個別 REQ{n}-{テーマ}/REQ{n}.{sub}-{名称}.md

# REQ{n}.{sub}: {名称}

[R{m}.{k} — {要求名称}](../../要求定義/R{m}-{要求テーマ}/R{m}.{k}-{要求名称}.md) を満たすため、{名称} の要件を定める。

## 要件

- {システムが満たすべき振る舞いを箇条書き}

仕様 — 新テーマ SPEC{n}-{テーマ}/README.md

# SPEC{n}: {テーマ}

[REQ{m} — {要件テーマ}](../../要件定義/REQ{m}-{要件テーマ}/README.md) の実装仕様。

仕様 — 個別 SPEC{n}-{テーマ}/SPEC{n}.{sub}-{名称}.md

# SPEC{n}.{sub}: {名称}

[REQ{m}.{k} — {要件名称}](../../要件定義/REQ{m}-{要件テーマ}/REQ{m}.{k}-{要件名称}.md) の{名称}に関する実装仕様。

## 設計

- {メソッド・データ構造・アルゴリズムなど具体的な実装方針を箇条書き}

用語集 用語集/{用語}.md

# {用語}

{定義を1〜2文で。平易に}

{補足や、markshelf／AI駆動開発の文脈での位置づけ}

※ 用語は他ドキュメントの本文に登場すると自動でリンクされる（src/lib/links.ts の displayName 自動マッチ）。ファイル名がそのままノード名になるので、本文で使う表記と一致させる。