docs: ドキュメント間の相互参照を改善 - #489
Conversation
- docs/README.md を新規作成（全体の索引ページ） - 各 setup ガイドに「関連ドキュメント」セクションを追加 - コマンド（setup-new-repo, setup-ci）から docs/setup への参照を追加 - README.md に docs/ ディレクトリの説明を追加 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
📝 WalkthroughWalkthroughAdds a docs/ index and many setup guide cross-links, introduces project-type presets and detection for DevContainer/config generation, updates Codespaces/devcontainer settings and VS Code configs, and applies spellcheck and gitignore updates; mostly documentation plus a new Changes
Sequence Diagram(s)mermaid CLI->>Presets: request detection rules Estimated code review effort🎯 4 (Complex) | ⏱️ ~45 minutes Possibly related PRs
Suggested labels
Poem
🚥 Pre-merge checks | ✅ 3✅ Passed checks (3 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
🔍 AI Code Review (Local Hook)Models: Codex (default) / Gemini (default) 🤖 Codex Review指摘事項はありません。ドキュメント追加・リンク整備のみで、正確性/性能/セキュリティ/保守性/開発者体験に影響する問題は見当たりません。 判定: patch is correct（ドキュメント更新のみで不具合導入の兆候なし） ✨ Gemini Reviewレビュー結果は以下の通りです。 発見された問題
全体的な評価patch is incorrect 理由: ドキュメントを再編成し、プロジェクト種別ごとのセットアップガイドを追加することで、情報の見通しを良くするという変更の意図は非常に価値があります。しかし、 信頼度: 0.9
|
コードレビュードキュメント間のナビゲーション改善という目的は明確で、全体的によくまとまった PR です。いくつか指摘事項があります。 🔴 要修正:
|
| 位置 | 内容 |
|---|---|
| Setup と Codespaces の間（新規追加） | [docs/setup/](../../docs/setup/README.md) |
| テーブル末尾（既存） | /changelog-generator |
同じカテゴリ名が非連続で出現すると、読み手が混乱します。
以下のいずれかで修正を推奨します：
案A: 両行を末尾の「Documentation」カテゴリにまとめる
| **Documentation** | `/changelog-generator` | Conventional Commits から CHANGELOG を生成 |
| | [docs/setup/](../../docs/setup/README.md) | プロジェクト種別ごとのセットアップガイド |案B: 新規追加行のカテゴリ名を "Setup Guides" などに変更してカテゴリを分ける
🟡 テスト計画が未チェック
PR 本文のテスト計画チェックボックスがすべて未チェックです。
ドキュメント PR ではリンク切れが主なリスクになるため、マージ前にリンクの動作確認を完了させてください。
（GitHub のプレビュー画面や markdown-link-check などが有効です）
✅ 確認済み: 参照先ファイルはすべて存在
docs/README.md から参照されている以下のファイルが存在することを確認しました：
AGENTS.md✅credentials/README.md✅script/README.md✅docs/mcp-servers-guide.md,docs/sentry-setup-guide.md,docs/tool-catalog.md,docs/using-config-base-image.md✅
✅ 相対パスは正確
.claude/commands/ からの ../../docs/setup/README.md は、
.claude/commands/ → .claude/ → (root) → docs/setup/README.md となり正しいです。
💬 軽微な提案
docs/README.md の「クイックスタート」セクションは非常に有用ですが、
/repo-maintenance → tool-catalog.md の対応関係はやや直感的でないかもしれません。
コメント等で補足するか、より関連性の高いコマンドとの対応を検討してください（必須ではありません）。
総評
ドキュメントの孤立を解消する価値ある変更です。重複カテゴリの修正とリンク確認を完了すれば LGTM です。
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 2
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In @.claude/commands/README.md:
- Around line 28-34: The table contains two separate "**Documentation**" rows
(one for "docs/setup/" and one for "/changelog-generator") which breaks
grouping; move the "/changelog-generator" row from the second
"**Documentation**" block into the "**Updates**" block (or consolidate both
Documentation rows into a single adjacent block) so related items like
"/update-claude-code", "/update-actions" and "/changelog-generator" are grouped
under "**Updates**" and the table reads consistently.
In `@docs/README.md`:
- Around line 54-69: Add a language tag to the fenced code block in
docs/README.md (the directory-tree code block) by changing the opening fence
from ``` to ```text so the block uses plain text syntax highlighting; locate the
fenced block showing the docs/ tree in README.md and update its opening fence
accordingly.
| ``` | ||
| docs/ | ||
| ├── README.md # このファイル（ドキュメント索引） | ||
| ├── setup/ # プロジェクト種別セットアップガイド | ||
| │ ├── README.md # 共通品質ゲート・パターン | ||
| │ ├── web-app-nextjs.md # Next.js | ||
| │ ├── spa-react-vite.md # React + Vite | ||
| │ ├── npm-library-cli.md # npm ライブラリ | ||
| │ ├── mobile-flutter.md # Flutter | ||
| │ ├── mobile-android.md # Android | ||
| │ └── desktop-extension-ts.md # デスクトップ拡張 | ||
| ├── using-config-base-image.md # DevContainer ベースイメージ | ||
| ├── mcp-servers-guide.md # MCP サーバー設定 | ||
| ├── sentry-setup-guide.md # Sentry セットアップ | ||
| └── tool-catalog.md # ツールカタログ | ||
| ``` |
There was a problem hiding this comment.
MD040: add a language tag to the fenced code block (flagged by markdownlint).
Specifying a language improves content rendering by using the correct syntax highlighting for code. For plain directory trees, text is the conventional value.
♻️ Proposed fix
-```
+```text
docs/
├── README.md # このファイル（ドキュメント索引）📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| ``` | |
| docs/ | |
| ├── README.md # このファイル（ドキュメント索引） | |
| ├── setup/ # プロジェクト種別セットアップガイド | |
| │ ├── README.md # 共通品質ゲート・パターン | |
| │ ├── web-app-nextjs.md # Next.js | |
| │ ├── spa-react-vite.md # React + Vite | |
| │ ├── npm-library-cli.md # npm ライブラリ | |
| │ ├── mobile-flutter.md # Flutter | |
| │ ├── mobile-android.md # Android | |
| │ └── desktop-extension-ts.md # デスクトップ拡張 | |
| ├── using-config-base-image.md # DevContainer ベースイメージ | |
| ├── mcp-servers-guide.md # MCP サーバー設定 | |
| ├── sentry-setup-guide.md # Sentry セットアップ | |
| └── tool-catalog.md # ツールカタログ | |
| ``` |
🧰 Tools
🪛 markdownlint-cli2 (0.21.0)
[warning] 54-54: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@docs/README.md` around lines 54 - 69, Add a language tag to the fenced code
block in docs/README.md (the directory-tree code block) by changing the opening
fence from ``` to ```text so the block uses plain text syntax highlighting;
locate the fenced block showing the docs/ tree in README.md and update its
opening fence accordingly.
|
(aside) |
|
Claude finished @keito4's task in 12m 30s —— View job コンフリクト解消完了 ✅
実施内容
コンフリクト解消ファイル:
全テスト（101件）・フォーマットチェック・Lintがすべて通過してコミット済みです。 |
feat/project-type-presets (#490) と feat/vscode-environment-enhancements (#491) のマージにより生じたコンフリクトを手動で解消。 - .claude/commands/setup-new-repo.md: --type/--interactive オプション、Step 3.5 (プロジェクトタイプ検出)、Step 9.5 (skills/plugins設定) を追加 - docs/setup/README.md: project-presets.json への参照と Note を追加 - .devcontainer/codespaces/devcontainer.json: CLAUDE_CONFIG_DIR を追加 - .devcontainer/templates/project-presets.json: 新規作成（プロジェクトプリセット定義） - .gitignore: cspell-custom-words.txt と .claude-data/ を追加 - .vscode/extensions.json: 推奨拡張機能を追加 - .vscode/settings.json: 詳細なエディタ設定を追加 - cspell.json, .vscode/cspell-custom-words.txt: スペルチェック設定を追加 Co-authored-by: keito4 <keito4@users.noreply.github.com>
There was a problem hiding this comment.
Actionable comments posted: 1
🧹 Nitpick comments (3)
.vscode/settings.json (2)
41-41:importModuleSpecifier: "relative"may conflict with path-alias setups in generated projects.When
/setup-new-repois used for Next.js projects (which commonly use@/or~/path aliases viatsconfig.paths), this workspace setting will override VS Code's auto-import to produce relative paths instead — which can be surprising. Since this is a shared.vscode/settings.jsonthatsetup-new-repopropagates to new repos (Step 5.4), consider whether"non-relative"or"shortest"would be a safer default.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In @.vscode/settings.json at line 41, The workspace setting "typescript.preferences.importModuleSpecifier": "relative" forces VS Code auto-imports to use relative paths which conflicts with Next.js/tsconfig path-aliases like "@/"; change the value to a safer default such as "non-relative" or "shortest" in .vscode/settings.json (replace the "relative" string), or remove the key so projects can control it per-repo—update the setting where "typescript.preferences.importModuleSpecifier" is defined to the chosen value to ensure auto-imports prefer path aliases.
6-6:editor.bracketPairColorization.enabled: trueis VS Code's default since v1.67 — no-op.Harmless to keep for explicitness, but it can be removed.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In @.vscode/settings.json at line 6, Remove the no-op setting "editor.bracketPairColorization.enabled": true from .vscode/settings.json; locate that exact key in the file and delete the line to avoid redundant configuration since VS Code defaults this behavior starting v1.67..devcontainer/templates/project-presets.json (1)
2-3:_detectionLogiccomment is incomplete —packageFields,directories, andextensionsdetection types are undocumented.The comment only explains
files(OR) andpackageDependencies(AND), but three other detection field types are used across presets:
packageFields(npm-library, L61): unclear whether["bin", "exports"]is OR (binorexportspresent) or AND (both required)extensions(terraform, L132): file extension scandirectories(android, L104): directory presence checkThe
packageFieldsOR/AND ambiguity is the highest-impact gap: if OR-semantics apply, any project withexportsin itspackage.jsoncould matchnpm-librarybeforenodejs. Detection order mitigates this at runtime, but the consumer implementing the detection logic may not infer the intended semantics.📝 Suggested addition to `_detectionLogic`
- "_detectionLogic": "detection 内の複数条件は AND で結合される（files のいずれか AND packageDependencies の全て）", + "_detectionLogic": "detection 内の複数条件は AND で結合される（files のいずれか AND packageDependencies の全て AND packageFields のいずれか AND directories の全て AND extensions のいずれか）",🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In @.devcontainer/templates/project-presets.json around lines 2 - 3, Expand the _detectionLogic comment to document semantics for all detection keys: state that files uses OR (any file matches), packageDependencies uses AND (all listed deps must exist), packageFields uses OR (any listed field present in package.json counts) and clarify extensions checks file extensions while directories checks for presence of named directories; reference the existing keys names _detectionLogic, files, packageDependencies, packageFields, extensions, and directories and mention npm-library as an example where packageFields like ["bin","exports"] are treated as OR to avoid ambiguity with nodejs detection.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In @.claude/commands/setup-new-repo.md:
- Line 79: The document's detection rule for the spa-react preset only mentions
`@vitejs/plugin-react` but project-presets.json requires both "react" and
"@vitejs/plugin-react"; update the text on the spa-react detection (line
referencing `@vitejs/plugin-react`) to require/check for both packageDependencies
entries (react and `@vitejs/plugin-react`) so the written detection matches the
actual preset definition in project-presets.json and implementers won't skip the
react dependency check.
---
Nitpick comments:
In @.devcontainer/templates/project-presets.json:
- Around line 2-3: Expand the _detectionLogic comment to document semantics for
all detection keys: state that files uses OR (any file matches),
packageDependencies uses AND (all listed deps must exist), packageFields uses OR
(any listed field present in package.json counts) and clarify extensions checks
file extensions while directories checks for presence of named directories;
reference the existing keys names _detectionLogic, files, packageDependencies,
packageFields, extensions, and directories and mention npm-library as an example
where packageFields like ["bin","exports"] are treated as OR to avoid ambiguity
with nodejs detection.
In @.vscode/settings.json:
- Line 41: The workspace setting "typescript.preferences.importModuleSpecifier":
"relative" forces VS Code auto-imports to use relative paths which conflicts
with Next.js/tsconfig path-aliases like "@/"; change the value to a safer
default such as "non-relative" or "shortest" in .vscode/settings.json (replace
the "relative" string), or remove the key so projects can control it
per-repo—update the setting where "typescript.preferences.importModuleSpecifier"
is defined to the chosen value to ensure auto-imports prefer path aliases.
- Line 6: Remove the no-op setting "editor.bracketPairColorization.enabled":
true from .vscode/settings.json; locate that exact key in the file and delete
the line to avoid redundant configuration since VS Code defaults this behavior
starting v1.67.
| 2. pubspec.yaml が存在 → flutter | ||
| 3. build.gradle* + app/src/main/ が存在 → android | ||
| 4. vite.config.* + package.json に @vitejs/plugin-react → spa-react | ||
| 5. package.json に @raycast/api 依存 → raycast |
There was a problem hiding this comment.
Documentation–preset mismatch for spa-react detection.
Line 79 states the detection condition as @vitejs/plugin-react only, but project-presets.json requires both react and @vitejs/plugin-react in packageDependencies:
"packageDependencies": ["react", "@vitejs/plugin-react"]Anyone implementing the detection logic from this document would miss the react dependency check.
📝 Suggested fix
-4. vite.config.* + package.json に `@vitejs/plugin-react` → spa-react
+4. vite.config.* + package.json に react かつ `@vitejs/plugin-react` → spa-react🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In @.claude/commands/setup-new-repo.md at line 79, The document's detection rule
for the spa-react preset only mentions `@vitejs/plugin-react` but
project-presets.json requires both "react" and "@vitejs/plugin-react"; update
the text on the spa-react detection (line referencing `@vitejs/plugin-react`) to
require/check for both packageDependencies entries (react and
`@vitejs/plugin-react`) so the written detection matches the actual preset
definition in project-presets.json and implementers won't skip the react
dependency check.
|
🎉 This PR is included in version 1.80.0 🎉 The release is available on GitHub release Your semantic-release bot 📦🚀 |
1 participant
Summary
Background
docs/setup/ディレクトリのセットアップガイドが孤立しており、どこからも参照されていなかった。これにより、ドキュメント間のナビゲーションが困難になっていた。
Changes
新規作成
docs/README.md: ドキュメント全体の索引ページ関連ドキュメントセクションを追加
docs/setup/README.mddocs/setup/web-app-nextjs.mddocs/setup/spa-react-vite.mddocs/setup/npm-library-cli.mddocs/setup/mobile-flutter.mddocs/setup/mobile-android.mddocs/setup/desktop-extension-ts.mdコマンドへの参照追加
.claude/commands/setup-new-repo.md: Project Type Guides セクション追加.claude/commands/setup-ci.md: Project Type Guides 参照追加.claude/commands/README.md: docs/setup を Quick Reference に追加README.md: docs/ ディレクトリの説明を追加Test plan
🤖 Generated with Claude Code
Summary by CodeRabbit
Documentation
New Features
Chores