Docs: markdown-writing skill を第三者可読性ルールへ拡張 (NDF v4.20.0)#59
Merged
Conversation
- 適用対象に仕様書・PR本文・調査レポート・レビューコメントを追加 - 内部識別子（テーブル名・カラム名）やローカル略語を説明文に持ち込まない ルールを追加 - 検討過程の痕跡（案A / Option A 等）と変更履歴を本文に残さないルールを追加 - 否定的結論にエビデンスを必須とするルール、個人情報・認証情報を含めない ルールを追加 - 書き終えた後の grep セルフチェックとチェックリストを整備 - 4ランタイム（shared / claude / codex / kiro）へ同期し、NDF を v4.20.0 に更新 - cross-review 関連の issue plan（issue-33 / issue-37）を追加 - Serena バージョンアップに伴う .serena/*.yml の自動更新を取り込み Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01YGaN4qDNqNCVcBGqzEr1RS
mermaid は図を表示領域の幅に収めて縮小するため、横に広い図ほど文字が 小さくなり読めなくなる。この制約と対処（縦方向レイアウト、ラベル短縮、 図の分割、participant 数の上限）を 01-diagram-guide.md に明記した。 4ランタイム（shared / claude / codex / kiro）へ同期済み。 Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01YGaN4qDNqNCVcBGqzEr1RS
mermaid 11.16.0 を chromium で実際にレンダリングし、図の自然幅と 本文幅（GitHub 890px / Notion 708px）から実効文字サイズを計測した。 日本語ラベルのノードは1個あたり約215px を消費し、GitHub では5個から、 Notion では4個から縮小が始まる。7個では GitHub で 9.7px、Notion で 7.7px まで縮み、実質読めない。 当初記載の「5〜7個まで」は過大だったため、上限を3個（4個を超えない）に 修正し、実測値の対応表とラベル長による差（短ラベルなら GitHub 6個まで 等倍）を追記した。シーケンス図の participant 上限も同様に修正。 4ランタイム（shared / claude / codex / kiro）へ同期済み。 Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01YGaN4qDNqNCVcBGqzEr1RS
takemi-ohama
commented
Jul 21, 2026
takemi-ohama
left a comment
takemi-ohama
left a comment
Contributor
Author
There was a problem hiding this comment.
🤖 cross-review | round 1 | codex | REQUEST_CHANGES
修正が必要な点を2件インラインに記載しました。
takemi-ohama
commented
Jul 21, 2026
takemi-ohama
left a comment
takemi-ohama
left a comment
Contributor
Author
There was a problem hiding this comment.
🤖 cross-review | round 1 | gemini | COMMENT
Markdown 執筆ルールの拡充と実測値の反映を確認しました。
インラインにて、セルフチェック用コマンドの正規表現に関する微修正を 1件提案しています。
- セルフチェックの grep 実行のため allowed-tools に Bash / Grep を追加
- 識別子検出の正規表現を [a-z]+_[a-z0-9_]{2,} に修正し user_id / plan_id 等の2文字サフィックスを検知
- .serena/serena_config.yml の trusted_project_path_patterns から '**' を削除し空に変更
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
takemi-ohama
commented
Jul 21, 2026
takemi-ohama
left a comment
takemi-ohama
left a comment
Contributor
Author
There was a problem hiding this comment.
🤖 cross-review | round 2 | gemini | APPROVE
本PRの変更（markdown-writing skill の可読性ルール拡張）について確認しました。指摘事項はありません。
takemi-ohama
commented
Jul 21, 2026
takemi-ohama
left a comment
takemi-ohama
left a comment
Contributor
Author
There was a problem hiding this comment.
🤖 cross-review | round 2 | codex | APPROVE
追加の修正要求はありません。round 1 の既存指摘は現 head で対応済みとして確認しました。
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
markdown-writingskill を、体裁ルール中心の内容から第三者が読んで理解できる文章を書くためのルールへ拡張しました。適用対象に仕様書・PR 本文・調査レポート・レビューコメントを追加しています。1. 第三者可読性のルールを追加（SKILL.md）
2. mermaid 図の横幅ルールを追加（01-diagram-guide.md）
mermaid は図の自然幅が本文幅を超えると図全体を縮小するため、横に長い図は文字が読めなくなります。この制約を実測して明文化しました。
mermaid 11.16.0 を Chromium で実際にレンダリングし、SVG の自然幅から実効文字サイズを算出した結果（本文16px 基準）:
日本語ラベル（6文字程度）のノードは1個あたり約215px を消費し、GitHub は5個から、Notion は4個から縮小が始まります。この実測に基づき 横方向の要素は3個まで（4個を超えない） を上限としました。あわせて以下を記載しています。
graph TDで縦方向にする /<br/>でラベルを改行する / 図を分割する3. その他
ndf-shared/ndf-claude/ndf-codex/ndf-kiro）へscripts/build-runtime-plugins.shで同期し、NDF プラグインを v4.20.0 に更新（plugin.json× 2 /marketplace.json/README.md/AGENTS.md）issues/issue-33-cross-review-resume-open-threads.md、issues/issue-37-cross-review-reply-resolve-guard.md）— 本 PR では plan の追加のみで、cross-review skill 本体の実装変更は含みません.serena/*.ymlの自動更新を取り込みTest plan
plugins/ndf-sharedと 3ランタイム配布物のmarkdown-writing/が完全一致することを diff で確認claude plugin validateが通過marketplace.json/plugin.json× 2 /README.md/AGENTS.mdで揃っていることやらないこと