nx-workspace-patterns

nx-workspace-patterns スキルの概要

nx-workspace-patterns が解決すること

nx-workspace-patterns は、単に「Nx を使うべき」といった一般論ではなく、実運用に耐える構成判断をもとに Nx モノレポを設計・整理するためのスキルです。とくに、わかりやすいワークスペース構成、強制できるプロジェクト境界、CI での affected command の改善、長期運用を見据えたライブラリ分類が必要な場合に力を発揮します。

向いている読者

このスキルが特に合うのは、次のようなエンジニア、テックリード、AI を活用してリポジトリを管理する担当者です。

• 新しい Nx workspace を立ち上げたい
• 既存の monorepo を Nx に移行したい
• プロジェクト間の結合を減らしたい
• キャッシュや affected runs を使って build performance を改善したい
• apps、libs、shared code の切り分け方を決めたい

実際に片付けたい仕事

多くのユーザーが必要としているのは、Nx の理論講座ではありません。apps/、libs/、tools/、nx.json、そして project boundaries を、リポジトリ規模・チーム構成・CI 要件に合わせて再現可能な形で設計するためのパターンです。nx-workspace-patterns の価値は、「Nx を正しくセットアップしたい」という曖昧な要望を、具体的な workspace 構成と naming model に落とし込める点にあります。

nx-workspace-patterns を差別化するポイント

nx-workspace-patterns の最大の強みは、プロダクション前提の workspace pattern に焦点を当てていることです。

• monorepo 向けのアーキテクチャ構成
• feature、ui、data-access、util、shell といった library type の慣習
• boundary を意識した構成
• affected commands や caching など、CI を前提にした Nx 活用

そのため、AI に「Nx の構成を提案して」とだけ投げる汎用的な prompt よりも、判断材料として使いやすい内容になっています。

インストール前に知っておきたいこと

これは automation package ではなく、あくまでガイダンス用のスキルです。この repository path には helper scripts、generators、reference assets は含まれていません。価値の中心は SKILL.md に整理された構成パターンなので、導入判断のポイントは「そのまま使える完成済みツールチェーンが欲しいか」ではなく、「自分の環境に合わせて調整できる architecture guidance が欲しいか」です。

nx-workspace-patterns スキルの使い方

nx-workspace-patterns のインストール前提

このスキルは、GitHub-hosted skills を扱える agent や AI workflow の中で使います。環境が一般的な Skills の導入フローに対応しているなら、まず repository を追加し、その後 Nx workspace の設計・移行・最適化を相談したい場面で nx-workspace-patterns を呼び出します。

よくある install パターンは次のとおりです。

npx skills add https://github.com/wshobson/agents

その後、AI workflow から nx-workspace-patterns をスキル名で指定して呼び出します。

最初に読むべきファイル

まず確認するのは次のファイルです。

• plugins/developer-essentials/skills/nx-workspace-patterns/SKILL.md

このスキルフォルダには追加の resources/、rules/、helper scripts はないため、実際に使えるガイダンスの大半はこの 1 ファイルにまとまっています。

スキルに渡すべき入力

nx-workspace-patterns は、汎用的な Nx の例を求めるよりも、リポジトリ固有の制約を渡したほうがはるかに有効です。たとえば次の情報が役立ちます。

• 現在の repo type: polyrepo、monorepo、または partial migration
• frontend/backend stack
• apps と shared packages の数
• team ownership boundaries
• 現在の pain points: slow CI、circular deps、曖昧な shared code、弱い caching
• 目標状態: より速い affected runs、より厳格な boundaries、再利用しやすい code

ざっくりした要望を強い prompt に変える

弱い prompt:

Help me use Nx.

より良い prompt:

Use nx-workspace-patterns to propose an Nx workspace for 3 apps (web, admin, api) and shared libraries. We want strict boundaries, affected-based CI, and remote caching. Suggest folder structure, library types, naming conventions, and example nx.json defaults.

最も良い prompt:

Use nx-workspace-patterns for Project Setup. We are migrating a TypeScript monorepo with React apps and a Node API into Nx. Current issues: shared code is mixed together, CI runs everything, and teams accidentally import across domains. Propose:

1. workspace layout for apps/, libs/, and tools/
2. a library taxonomy using feature, ui, data-access, util, shell
3. tagging and boundary rules
4. affected-command CI workflow
5. remote cache rollout steps
6. migration order with low-risk first moves

情報の多い prompt ほど、実際に実装へ落とし込める architecture を nx-workspace-patterns が返しやすくなります。

実務で使いやすい nx-workspace-patterns の進め方

nx-workspace-patterns を高精度で使うなら、次の流れが効果的です。

1. 現在の repo の状況と痛みを説明する
2. 目標となる workspace 構成を提案してもらう
3. dependency boundary rules と naming conventions を求める
4. affected runs を前提にした CI commands を聞く
5. 出力を実際の deployment と team ownership model に照らして見直す
6. 一括リライトではなく phased migration plan を求める

この流れが重要なのは、Nx の設計判断が後から効いてくるためです。見た目のきれいなフォルダ構成だけでは、dependency rules や CI strategy が伴わない限り不十分なことが多いです。

nx-workspace-patterns が特に強いパターン

元の内容で特に強いのは次の領域です。

• Nx architecture layout
• app/lib separation
• library type classification
• project boundary thinking
• affected commands を使った CI optimization の方向づけ
• remote caching を運用面の課題として扱う視点

このあたりが判断ポイントなら、nx-workspace-patterns usage は汎用的な monorepo prompt よりかなり有用です。

先に棚卸ししたい repository files と概念

スキルを自分の repo に当てる前に、まず次を整理しておくと進めやすくなります。

• deployable apps
• 再利用可能な shared code
• domain-specific business logic
• API と state management layers
• utility-only modules
• tools/ 配下に置くべき custom tooling 候補

これを先に切り分けておくと、nx-workspace-patterns の library type model をきれいに適用しやすくなります。

library type model をうまく使うコツ

このスキルの library taxonomy は、とても実用性の高い要素のひとつです。

• feature: business logic と smart components
• ui: 表示用の部品
• data-access: API と state integration
• util: 純粋な helper
• shell: app composition と bootstrapping

これらのラベルは飾りとして付けるのではなく、imports を制限するために使うべきです。たとえば ui は軽量で再利用しやすい状態を保つのが基本で、feature は無関係な shared helpers の捨て場にしてはいけません。

CI 最適化で nx-workspace-patterns が効く場面

Nx 導入の主目的が CI の高速化なら、nx-workspace-patterns に次を明示的に求めるのがおすすめです。

• affected command strategy
• cacheable target suggestions
• nx.json における task defaults
• remote caching の rollout 順序
• performance tuning 前に片付けるべき dependency boundary の整理

これにより、「workspace graph が安定する前に caching を最適化しようとする」というよくある失敗を避けやすくなります。

向いていないケース

nx-workspace-patterns install に次の役割まで期待しないでください。

• 公式の Nx package installation docs の代替
• framework-specific generators の代替
• executor/plugin 選定の詳細ガイド
• バージョンごとの厳密な migration commands

package compatibility matrix や plugin 固有の setup が必要なら、このスキルと公式 Nx docs を併用するのが適切です。

nx-workspace-patterns スキル FAQ

nx-workspace-patterns は初心者向けですか？

はい。ただし monorepo の概念はすでに理解していて、構造上の判断を助けてほしい人に向いています。CLI setup、generators、target execution といった Nx の基礎から必要な完全な初心者には、そこまで相性がよくありません。

通常の AI prompt より nx-workspace-patterns のほうがいいですか？

アーキテクチャ設計では、たいていその通りです。nx-workspace-patterns skill は、workspace layout、library の役割、CI を前提とした設計に対して、より意図のある枠組みをモデルに与えます。通常の prompt だと、dependency の意図が曖昧なまま generic な folders が返ってきがちです。

移行にも使えますか？ それとも greenfield setup 専用ですか？

両方に対応できます。特に migration planning では、目標となる taxonomy と boundary model を示してくれる点が有効です。既存 repo の移行では、段階的な移動、暫定的な compatibility rules、リスクの低い refactor から始める案を求めると使いやすくなります。

nx-workspace-patterns が深くカバーしない部分は何ですか？

少なくともこの repository には、次のような補助ファイルは含まれていないようです。

• automated validation
• custom scripts
• generator code
• organization-specific rule packs

そのため、完全な Nx platform kit ではなく、pattern guide として扱うのが適切です。

nx-workspace-patterns は Project Setup 専用ですか？

いいえ。nx-workspace-patterns for Project Setup は強いユースケースのひとつですが、既存 workspace の boundary を引き締めたいとき、libraries を再編したいとき、caching を導入したいとき、affected-based CI を改善したいときにも役立ちます。

小さな app が 1 つだけでも使うべきですか？

おそらく、まだ早いです。小規模な app が 1 つだけで shared code も少ないなら、Nx の構成はメリットよりオーバーヘッドのほうが大きくなりがちです。複数 app がある、shared code が増えている、team ownership がまたがり始めている、といった段階でこのスキルの価値は上がります。

nx-workspace-patterns スキルをより良く使うには

最初から具体的な repo 制約を渡す

nx-workspace-patterns の出力品質を最も手早く上げる方法は、最初から次の情報を渡すことです。

• app 数
• tech stack
• ownership boundaries
• 現在の dependency problems
• CI の pain points
• 希望する migration speed

ここが曖昧だと、スキルは generic な workspace template を返すしかありません。

フォルダ構成だけでなく boundary rules も求める

よくある失敗は、見た目の整った directory tree を受け入れてしまい、強制可能な architecture が定義されていないことです。次の点まで nx-workspace-patterns に明示させてください。

• 許可される import の方向
• tagging strategy
• 禁止すべき dependencies の例
• cross-cutting utilities の置き場所

ここまで詰めると、nx-workspace-patterns usage を実運用に乗せやすくなります。

散らかったコード配置の実例を渡す

現在の repo で shared code の置き場が曖昧なら、実在する module を 5〜10 個ほど渡して、それぞれをどこへ移すべきか聞くのが有効です。

• auth hooks
• API clients
• formatting helpers
• dashboard widgets
• app bootstrap code

こうすることで、feature、ui、data-access、util、shell の分類精度が上がります。

migration sequencing を依頼する

既存 repo に対しては、たとえば次のような順序立てた plan を求めると有効です。

1. apps と top-level libs を定義する
2. utilities を分離する
3. data-access modules を移す
4. tags と boundaries を強制する
5. CI を affected commands に更新する
6. remote caching を有効化する

一発で理想図だけ出してもらうより、移行リスクを下げやすい進め方です。

提案内容を実際の CI に照らして検証する

nx-workspace-patterns guide の提案は、CI 環境が前提を満たしてはじめて効果が出るものもあります。最初の出力を受けたら、続けて次を確認するとよいです。

• 最初に cacheable にすべき targets はどれか
• どの jobs から affected runs に切り替えるべきか
• remote cache の利用可否に依存する前提は何か
• 新しい構成で run time が改善したかどうかをどう測るか

初回回答のあとに prompt を磨く

2 回目の prompt として有効なのは、たとえば次のような形です。

Revise the nx-workspace-patterns proposal for a team of 4 squads with separate ownership over web, admin, api, and shared platform code. Add project tags, import rules, and examples of bad boundaries to avoid.

このような反復のほうが、「もっと詳しく」とだけ頼むより、判断を鋭くできます。

過剰設計に注意する

もうひとつの典型的な失敗は、library type を最初から全部導入してしまうことです。repo がまだ小さいなら、今必要な最小限の Nx structure と、後から層を増やす判断基準を提案するようスキルに依頼してください。そうすれば、workspace を早い段階で複雑にしすぎずに済みます。

公式 Nx docs と組み合わせて使う

nx-workspace-patterns install と実装をうまく進めるには、architecture の判断はこのスキル、次のような実装詳細は公式 Nx docs、という使い分けが有効です。

• exact commands
• plugin setup
• version-specific config changes
• executor と generator の詳細

どちらか片方だけに頼るより、この組み合わせのほうが良い結果になりやすいです。