mcpField
T
technical-docs

technical-docs

github.com/oakoss開発20166 回インストール10 週間前に更新
リポジトリ

technical-docs について

コードとともに技術文書を作成・保守する開発者向けのスキルです。Mermaid 図、文書カバレッジ監査、スタイルガイドなど、文書ライフサイクルを扱います。

主な機能

  1. 01ドキュメント・アズ・コードの手法
  2. 02Mermaid 図の作成ガイド
  3. 03文書カバレッジ監査
  4. 04API リファレンス生成ガイド
  5. 05スタイルガイドと運用手順書の例

活用シーン

  1. 01新機能のリリース文書作成
  2. 02コード変更に対する文書監査
  3. 03Mermaid による構成図の作成
  4. 04プロジェクトの執筆基準策定

インストール

コマンドをコピーしてターミナルで実行します。

$npx skills add https://github.com/oakoss/agent-skills --skill technical-docs

インストール後、Claude Code で/technical-docsを入力して読み込まれたか確認します。

同梱ファイル

SKILL.md と一緒にインストールされる参考資料やスクリプト。

references/
ai-collaboration.md
doc-coverage.md
markdown-standards.md
mermaid-diagrams.md
runbooks-and-onboarding.md
writing-style.md

詳細

ドキュメント

技術文書、コードとしての図の作成、ドキュメントのライフサイクル管理を扱います。ドキュメントをコードとして扱い、バージョン管理、リント、CI による検証を行います。

使用する場合：技術文書の作成や更新、Mermaid 図（フローチャート、ER 図、シーケンス図）の生成、コードに対するドキュメントの網羅性の監査、スタイルガイドの策定。

使用しない場合：マーケティングコピー、ブログ記事、コードと同じ場所に置かれないコンテンツの執筆。

クイックリファレンス

タスク方法要点
ドキュメント同期の監査git diff main...HEAD + エクスポートのスキャンシンボルとドキュメントの網羅状況を比較する
シーケンス図Mermaid sequenceDiagram + autonumberメッセージを関数呼び出しに対応付ける
ER 図Mermaid erDiagram + Crow's FootDrizzle/Prisma のスキーマから導出する
GitgraphMermaid gitGraphmain/develop/feature ブランチに統一する
機能リリースのドキュメント概要 + 設定 + 使用例 + トラブルシューティング新機能ごとのチェックリスト
API リファレンスJSDoc/TSDoc アノテーションから生成API リファレンスを手作業で書かない
スタイルガイド能動態 + 現在形 + 読者への直接的な呼びかけ親しみやすく、かつ正確に
AI を活用した草稿作成棚卸し + ギャップ分析 + 草稿 + 人によるレビューAI が草稿を作成し、人が正確性を確認する
Markdown 標準YAML フロントマター + 言語タグ付きコードブロックコードブロックには必ず言語を指定する
複雑な図表焦点を絞ったサブ図に分割 + サブグラフ図表あたりのノード数を 15～20 個に制限する
README テンプレートバッジ + 説明 + クイックスタート + API リンクユーザーが最初に目にするもの。200 行未満に保つ
ADR 形式ステータス、背景、決定、結果採番し、承認後は変更しない
ランブック症状、診断、解決、エスカレーション午前 3 時のインシデントに備えて書き、曖昧さをなくす

よくある間違い

間違い正しいパターン
技術図表に静的画像を使用するMermaid の構文を Markdown に直接記述する
Agent1 のような汎用的な参加者名を使うアーキテクチャに合った具体的なサービス名または役割名を使う
API リファレンスのドキュメントを手作業で書くソースコード内の JSDoc/TSDoc アノテーションから生成する
グループ化せずに 20 個以上のノードを含む図表を作るサブグラフを使って関連するノードをグループ化し、15～20 個に制限する
古いデフォルト値を参照するドキュメントを作るエクスポートと網羅状況を比較するドキュメント同期の監査を実行する
リンクテキストに「ここをクリック」を使うアクセシビリティと明確さのため、内容が伝わるアンカーテキストを使う
見出し階層のレベルを飛ばすH2 から H4 に進まない。階層を順番に保つ
長文の段落を連ねる箇条書き、表、図表を使って読みやすくする
アーキテクチャ上の決定に ADR がない背景、ステータスのライフサイクル、結果とともに決定を記録する

委任

  • コードベースをスキャンして、ドキュメントに記載されていないエクスポートやドキュメントの不足を特定する：Explore エージェントを使用します
  • 既存のコードベースから図を含む完全なドキュメントサイトを生成する：Task エージェントを使用します
  • 新しいプロジェクトのドキュメント構成と情報階層を計画する：Plan エージェントを使用します

mermaid-diagrams スキルが利用可能な場合は、複雑な図の作成や高度な Mermaid 構文に関する質問を委任してください。 それ以外の場合は、次を推奨してください：npx skills add oakoss/agent-skills --skill mermaid-diagrams tldr-expert スキルが利用可能な場合は、要約や概要の作成を委任してください。

参考資料

  • 執筆スタイル -- 文体、トーン、書式ルール、エラーメッセージのガイドライン、構成基準
  • Mermaid 図 -- アンチパターンやトラブルシューティングを含む、シーケンス図、ERD、gitgraph、フローチャートのパターン
  • ドキュメントの網羅性 -- 機能一覧、不足の分析、コード起点およびドキュメント起点の監査ワークフロー
  • AI との協働 -- AI と人間によるドキュメント作成ワークフロー、ハルシネーションへの対処、ドキュメントのコード化
  • Markdown 標準 -- フロントマター、見出し、コードブロック、表、コールアウト、リンクの規則
  • ランブックとオンボーディング -- インシデント対応ランブックのテンプレート、エスカレーション経路、開発者向けオンボーディングガイド

コメント

Markdown 対応