mcpField
D
design-sync

design-sync

github.com/chmouelテスト・品質31362 回インストール今日更新
リポジトリ

design-sync について

DESIGN.md が現在のコードアーキテクチャと一致しているかを確認するスキルです。Go プロジェクトの開発者向けに、ディレクトリ、参照、インポート、テーマ項目の情報から文書のずれと更新案を特定します。

主な機能

  1. 01ディレクトリ構成と文書の比較
  2. 02ファイル参照と行番号の確認
  3. 03最近のアーキテクチャ変更の確認
  4. 04内部パッケージのインポート比較
  5. 05テーマ項目の文書と実装の照合
  6. 06文書の更新時期の確認

活用シーン

  1. 01リファクタリング後の設計文書の点検
  2. 02コミット前の DESIGN.md 参照確認
  3. 03大規模な変更後の文書更新計画

インストール

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

$npx skills add https://github.com/chmouel/lazyworktree --skill design-sync

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

詳細

DESIGN.md 同期チェック

DESIGN.md が現在のコードベースのアーキテクチャを正確に反映しているか確認します。

現在のディレクトリ構造

!ls -la internal/ | grep '^d'

DESIGN.md のディレクトリセクション

!sed -n '/^## Directory Structure/,/^## /p' DESIGN.md | head -50

DESIGN.md に記載されている重要なファイル参照

!grep -oE 'internal/[a-z/]+\.go:[0-9]+-[0-9]+' DESIGN.md | sort -u

DESIGN.md の最終更新以降の変更

!git log --since="$(git log -1 --format=%ai DESIGN.md 2>/dev/null || echo '1 month ago')" --name-only --oneline -- 'internal/**/*.go' | grep -E '^internal/' | sort -u

現在のパッケージインポートグラフ

!go list -f '{{.ImportPath}}: {{join .Imports ", "}}' ./internal/... 2>/dev/null | grep 'lazyworktree/internal' | head -30

DESIGN.md のメタデータ

!head -20 DESIGN.md | grep -E '(Last updated|Version)'

ドキュメントに記載されたテーマフィールドと実際のフィールド

!echo "=== Documented theme fields ===" && grep -A 20 'type Theme struct' DESIGN.md | grep -oE '^\s+[A-Z][a-zA-Z]+' | wc -l && echo "=== Actual theme fields ===" && grep -A 30 'type Theme struct' internal/app/theme.go | grep -oE '^\s+[A-Z][a-zA-Z]+' | wc -l

分析の指示

上記のデータに基づいて、次の点を確認してください。

1. ディレクトリ構造の乖離
  • DESIGN.md に記載されていない新しいディレクトリが internal/ 配下にありますか？
  • ドキュメントに記載されたディレクトリは削除または名前が変更されていますか？
  • 実際のディレクトリ一覧と、ドキュメントの構造セクションを比較してください
2. 重要なファイル参照
  • DESIGN.md のすべての file:line-range 参照を抽出します（例：app.go:77-210）
  • 参照ごとに次の点を確認します。
    • そのパスにファイルが引き続き存在するか
    • 行番号が、記載されたコードセクションを引き続き指しているか
    • リファクタリングで行番号がずれている場合は、新しい正しい行番号を報告します
  • 壊れた参照や大幅な乖離を報告します
3. 最近のアーキテクチャ変更
  • DESIGN.md の最終更新以降に変更されたファイルを確認します
  • 変更がドキュメントに記載された抽象化に影響するかを特定します。
    • BubbleTea の Model/Update/View パターン
    • Git サービスのセマフォ実装
    • 画面マネージャーのスタック
    • テーマシステム
    • 設定のカスケード
  • DESIGN.md の更新が必要と思われる重要なファイルへの変更にフラグを付けます
4. インポートグラフの整合性
  • 現在のパッケージインポートと、ドキュメントに記載された依存関係グラフを比較します
  • DESIGN.md に記載されていない、新しい内部依存関係にフラグを付けます
  • すでに削除されているのに、引き続き記載されている依存関係にフラグを付けます
  • ドキュメントに記載されたパターンに反する循環依存がないか確認します
5. テーマシステムの正確性
  • ドキュメントと実際のコードでテーマフィールド数が一致するか確認します
  • 数が異なる場合は、ドキュメントに記載されていないフィールドを特定します
6. 古さの確認
  • DESIGN.md が90日を超えて更新されていない場合は報告します
  • 構造に変更があった場合は、「Last updated」の日付の更新を提案します

レポート形式

次の形式で出力してください。

✅ 最新の状態
  • 現在も正確で同期されている具体的な項目を一覧表示します
⚠️ 軽微な更新が必要
  • 行番号の修正（例：app.go:77-210 → app.go:87-220）
  • ドキュメントに追加すべき新しいディレクトリ
  • 軽微なインポートグラフの変更
  • テーマフィールド数の不一致
🔴 大幅な更新が必要
  • ドキュメントに記載されていない新しい抽象化やコンポーネント
  • 削除された、または大幅に変更されたドキュメント記載のコンポーネント
  • 変更されたアーキテクチャ上の判断
  • 壊れたファイル参照
📝 推奨する対応
  1. 更新する DESIGN.md の行番号を含め、具体的な編集内容を記載します
  2. 追加する新しいセクションを提案します（内容の概要も記載）
  3. 削除または書き直すセクションを記載します
  4. すべてのファイル参照について、行番号の修正を記載します

使用手順

/design-sync を呼び出すタイミング

事前に実行する場合（コミット前）：

  • internal/ 配下に新しいパッケージを追加したとき
  • 重要なファイル（app.go、service.go、model.go など）をリファクタリングしたとき
  • アーキテクチャパターン（Model-Update-View、セマフォなど）を変更したとき
  • 新しい画面タイプまたはテーマフィールドを追加したとき
  • 設定のカスケードまたは優先順位ルールを変更したとき

定期的に実行する場合：

  • 四半期ごとのメンテナンスレビュー
  • メジャーリリースの前
  • 大規模なアーキテクチャ関連の PR をマージした後
  • DESIGN.md が古くなったと感じたとき
推奨ワークフロー
# 1. Make architectural changes

# 2. Run design-sync skill
/design-sync

# 3. Review output for needed updates

# 4. Update DESIGN.md based on recommendations

# 5. Update "Last updated" date in DESIGN.md

# 6. Re-run to verify
/design-sync  # Should now show ✅ Up to Date

# 7. Commit changes together

コメント

Markdown 対応