naatin777/plugumi / .agents/skills/specbook-authoring
specbook-authoring
Verifieddocs/goals, requirements, architecture, designs, decisions, contracts, verification, guides 配下の Specbook 形式 Markdown/YAML ドキュメントの作成・編集・整理・手動レビュー。設計計画・機能要件・プロトコル決定・ドキュメント再構成・relation/frontmatter の確認に使う。旧Plugumi実装を既定仕様として使わない。
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 7.8 KB |
| references/architecture.md | markdown | 1.6 KB |
| references/contract.md | markdown | 1.5 KB |
| references/conventions.md | markdown | 5.5 KB |
| references/decision.md | markdown | 1.4 KB |
| references/design.md | markdown | 1.5 KB |
| references/goal.md | markdown | 1.3 KB |
| references/guide.md | markdown | 1.2 KB |
| references/japanese-writing.md | markdown | 5.6 KB |
| references/requirement.md | markdown | 1.4 KB |
| references/verification.md | markdown | 1.5 KB |
| templates/architecture.md | markdown | 557 B |
| templates/contract.md | markdown | 557 B |
| templates/decision.md | markdown | 434 B |
| templates/design.md | markdown | 580 B |
| templates/goal.md | markdown | 373 B |
| templates/guide.md | markdown | 362 B |
| templates/requirement.md | markdown | 386 B |
| templates/verification.md | markdown | 578 B |
references/japanese-writing.md
View on GitHub# 日本語の執筆・レビュー規約
Specbookの本文・見出し・Frontmatterの説明文を、日本語として読みやすく、かつ仕様として誤解されにくくするための指針。文章の校正に用い、**未決定の仕様を補完したり、意味を変えてはいけない**。
## 目標
読者が一度読んで、次の点を判断できる文章にする。
- **誰が**何をするのか(Core、Plugin、UI Host、利用者など)
- **どの条件で**何が起こり、何が保証されるのか
- **なぜ必要か**、ほかの選択肢とどう違うのか
- **決定済みか未決定か**、実装済みか構想段階か
短さよりも、読み返さずに正確に理解できることを優先する。
## 執筆ルール
1. **主語と責務を明示する。** 「状態を管理する」ではなく「CoreがLinkの状態を管理する」。省略しても誤読しない主語は繰り返さなくてよい。
2. **結論・条件・理由を分ける。** 判断を先に書き、根拠は後続の文で示す。例外や前提条件を省略しない。
3. **一文に複数の論点を詰め込まない。** 主語が変わる箇所、条件が重なる箇所、別の義務を列挙する箇所では文を分ける。文字数の一律上限は設けない。
4. **抽象語を具体化する。** 「柔軟」「自然」「適切」「効率的」「シームレス」「包括的」「最適化」などは、それだけで要件や目標を説明したことにしない。対象の操作・条件・変化を示す。
5. **名詞を重ねすぎない。** 「協調実行基盤状態管理機構」のような複合名詞は「実行状態を管理する仕組み」などに分解する。
6. **定義された技術用語を統一する。** Core / Plugin / Tool / Panel / Link等は `docs/glossary.md` に従う。似た概念を別名で呼ばない。一般的な英語は無理に混ぜず、専門語は無理に和訳しない。
7. **責務のレベルを混ぜない。** Plugumi全体が目指す価値、Platformの共通契約、個別Pluginの機能を区別する。Agent固有の例をCoreの必須仕様と誤認させない。
8. **見出しには内容が分かる名前を使う。** 「概要」「詳細」を繰り返すより「接続時にCoreが行うこと」「再接続後に無効になるID」など。見出しだけを追って話の流れが分かるようにする。
9. **箇条書きや表は比較・列挙に使う。** 連続した因果関係を断片的な箇条書きにしない。表にするとかえって読みにくい短い説明は文章にする。
10. **無意味な前置き・繰り返しを省く。** 「重要なのは〜という点である」「〜を実現することが可能となる」などを機械的に加えない。言い切る根拠がない強調表現も避ける。
「である」「です・ます」は文書内で混在させない。設計文書では簡潔な常体を基本とするが、既存文書の文体を一律に置換する必要はない。英文の規範語(MUST / SHOULD / MUST NOT)、識別子、JSONフィールド名、HTTPメソッドは文章校正のために変更しない。
## 書き換え例
### 主語を明らかにする
読みにくい例:
> Plugin登録後、適切な状態管理が行われ、必要に応じて再接続される。
改善例:
> CoreはPluginの登録情報を保持する。接続が切れた場合、Coreは設定されたPluginのEndpointへの接続を再試行する。
※ この例は**表現の違い**を示すもの。再接続の仕様を新たに決める根拠にはしない。
### 抽象的な価値を行動に落とす
読みにくい例:
> 人間とAIのシームレスな協調を可能にする。
改善例:
> AIが変更したファイルを、人間がWorkbenchから開いて確認できる。人間は必要に応じてAgentへ追加の指示を送れる。
※ Goalでは短い抽象表現を使ってよい。ただし、本文には具体例や観測できる証拠を添える。
### 対象範囲を分ける
読みにくい例:
> QueueとEventを共通化し、Agentの実行を効率化する。
改善例:
> PlatformはToolの途中経過や完了を通知する仕組みを提供する。Agent Pluginは受け取った通知を、独自のQueueにいつ渡すか判断する。
※ PlatformとAgent Pluginの責務を区別する例。実際の契約は該当文書を正本とする。
## レビュー手順
1. **内容:** 最初に「結論・理由・前提・対象外」が書かれているか確認する。段落ごとに話題を一つに絞る。
2. **読みやすさ:** 主語の欠落、長い修飾、抽象語、重複表現、同義語の揺れを直す。見出しを順に読むだけで内容の見当が付くか確認する。
3. **正確さ:** 原文と比べ、条件、例外、数値、MUST/SHOULD、責務の所在、決定/未決定、参照IDが変わっていないか確認する。
4. **変更の扱い:** 表現の改善と仕様変更を分離する。曖昧さが解消できない箇所は勝手に補完せず、曖昧な点として報告する。
## 最終チェック
- 「誰が・いつ・何を・どうなる」が必要な箇所で読み取れる
- 「柔軟」「自然」「適切」だけで説明が終わっていない
- Goal / Requirement / Design / Decision / Contract の役割が混ざっていない
- 同じ概念に異なる日本語・英語を使っていない
- 読みやすくするために要求の強さ、例外条件、未決定事項を消していない
- 読み手が次に読むべき関連文書をたどれる
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| brainstormingobra/superpowersYou MUST use this before any creative work - creating features, building components, adding functionality, modifying behavior, or planning anything new, in software or out of it (a talk, a business, a renovation). | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| brand-guidelinesanthropics/skillsApplies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| frontend-designanthropics/skillsGuidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| mcp-builderanthropics/skillsGuide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK). | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |