design-docs
Skill0 starsChanged 6 days agoMITView on GitHub
Creates and maintains a project's four design documents — requirements.md (why/for whom), specification.md (what to build), architecture.md (how, always-on policy), design.md (how, per-feature detail) — scaffolding them from templates and routing later changes to the right file. Use whenever a project's design docs need writing, setting up, scaffolding, or organizing ("設計ドキュメントを作って", "ドキュメントを整備して", "設計書を用意して") or updating after a change ("design.md を更新して", "ドキュメントを最新化して", "仕様変更をドキュメントに反映して", "この実装を設計書に反映して") — whether the user asks or a workflow step says to update the design docs, or to fix docs that drifted from the code.
8 other projects use a version of this.
Adopted by
Most recently taken up by
- reddygopalkrishna/developer-agent-skillstheir own version, first seen Nov 8, 2026
- OHNope/design-docs-kittheir own version, first seen Nov 1, 2026
- GoncaloPrata/ClaudeSkillstheir own version, first seen Nov 1, 2026
- ZaxbyHub/opencode-swarmtheir own version, first seen Oct 30, 2026
- zaxbysauce/opencode-swarmtheir own version, first seen Oct 8, 2026
- noir-lang/noirtheir own version, first seen Oct 8, 2026
Other versions8 projects use a version of this.
Word for word · 0
None found.
Edited · 0
None found.
Wrote their own version · 8
- noir-lang/noir★ 1.4ksame name
- zaxbysauce/opencode-swarm★ 519same name
- ZaxbyHub/opencode-swarm★ 518same name
- reddygopalkrishna/developer-agent-skills★ 8same name
- CaliLuke/skills★ 7same name
- alexjuda/alexjuda-skills★ 0same name
- GoncaloPrata/ClaudeSkills★ 0same name
- OHNope/design-docs-kit★ 0same name
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
In this repository13 other files it gives its agents.
- AGENTS.mdAGENTS.md
- create-issueSkill
- create-pullrequestSkill
- dotnet-scriptingSkill
- gyaruSkill
- hello-worldSkill
- ojousamaSkill
- python-scriptingSkill
- refactor-codeSkill
- resolve-issueSkill
- test-as-tddSkill
- test-codeSkill
- update-agentsmdSkill
The file
Files
design-docs Skill
requirements.md / specification.md / architecture.md / design.md の4ファイルを作成・更新します。
| ファイル | 段階 | 更新頻度 |
requirements.md | 前提（なぜ・誰のために作るか） | 要件が変わったときだけ |
specification.md | 何を作るか（顧客と合意する粒度） | 機能が変わったとき |
architecture.md | どう作るか・方針（常時読ませる） | 低い |
design.md | どう作るか・詳細（機能ごとに読ませる） | 高い |
各ファイルの守備範囲、更新頻度による切り分け、テストの扱い、どの図をどこで使うかの判断は 方針の抜粋 を読んでください。
最初に判定する
対象ディレクトリに4ファイルが存在するか調べ、モードを決めます。
- 1つも無い → 新規作成モード
- 1つ以上ある → 更新モード（既存ファイルは絶対に上書きしない）
- 一部だけある → 無いファイルは新規作成モード、あるファイルは更新モード
手順: 新規作成モード
- 配置先を確認する。既存の
docs/があればその配下、無ければリポジトリ直下。判断がつかなければユーザーに聞く。 assets/templates/の4ファイルを配置先へコピーする。- リポジトリの内容（README、コード、
AGENTS.md、Issue、ユーザーの説明）から確認できた事実だけを各節に書く。 - 確認できない箇所は
TBDと1行だけ残す。推測で埋めない。 埋められなかった項目はユーザーに提示して聞く。 - その案件に無い節（画面が無い、外部連携が無い等）は節ごと削除する。空の見出しを残さない。
- Mermaid の空ブロックは、実際に図を描く箇所だけ埋める。埋めない空ブロックは削除する。
完了後、次の一文を出力する。
architecture.mdは常時読ませたい情報です。AGENTS.mdにdocs/architecture.mdへの参照を1行追加することを推奨します。追加しますか？ユーザーが了承したら、
AGENTS.mdのKey Referencesに1行足す。
手順: 更新モード
- 何が変わったかを掴む。ユーザーの説明、
git diff、Issue、直前の実装内容を材料にする。 - 下のルーティング表で更新すべきファイルだけを選ぶ。無関係なファイルは開かない。
- 該当ファイルの該当節だけを差分更新する。全文の書き直しはしない。
- 変更後、ファイル間の整合を確認する。
specification.mdの機能がrequirements.mdの機能要件に無い → 要件の追加漏れdesign.mdのモジュールがarchitecture.mdのレイヤー構成に反する → どちらかが古い- コードと文書が食い違う → コードを正とし、文書を直す
- 更新した節と、変更しなかったファイルの理由を1行で報告する。
ルーティング表
| 変わったもの | 更新するファイル |
| 目的、想定利用者、要件、スコープ、非機能の目標値、受け入れ基準 | requirements.md |
| 機能、画面、画面遷移、データモデル、外部連携、エラーメッセージ | specification.md |
| 技術選定、ライブラリ、全体構成、レイヤー、依存の向き、共通規約、不変条件、テスト方針 | architecture.md |
| モジュール・クラス構成、処理の流れ、状態遷移、データアクセス、機能ごとのテスト観点 | design.md |
どちらに入れるか迷う情報は、その情報がどれくらいの頻度で変わるかで決めます。話題の近さで決めません。判断基準は 方針の抜粋 の「更新頻度による切り分けの原則」。
ADR の更新は追記のみ
architecture.md の技術選定の記録は、一度書いた項目を書き換えません。決定が変わったら新しい記録を足し、古い記録から新しい記録へリンクします。「いつ・なぜ方向が変わったか」を消さないためです。
書かないこと
- テストケース・テスト手順 — テストコードを正とします。文書に書くのは方針（
architecture.md）と観点（design.md）まで tasks.md/ 実装タスク一覧 — このスキルの範囲外です。着手中の作業は GitHub Issue で管理します- サンプル本文の創作 — 確認できないことは
TBDにしてユーザーに聞きます - コードを読めば分かること — 関数シグネチャの転記、ディレクトリ一覧
- 維持できない粒度の記述 — 更新されない設計ドキュメントは「間違った地図」になります
既存ファイルの扱い
requirements.md / specification.md / architecture.md / design.md を確認なしに上書き・全面書き換えしません。既存ファイルを大きく作り直す必要があると判断した場合は、節ごとの分類（残す / 消す / 別ファイルへ移す）を理由付きの表で示し、差分を提示して、ユーザーの承認を待ちます。
参考資料
- 方針の抜粋 — 判断基準
- テンプレート —
requirements.md/specification.md/architecture.md/design.md
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.