senior-fullstack

シニアフルスタック

プロジェクトのスキャフォールディングとコード品質分析ツールを備えたフルスタック開発スキルです。

---

目次

• トリガーフレーズ
• ツール
• ワークフロー
• リファレンスガイド

---

トリガーフレーズ

次のような依頼があった場合に、このスキルを使用します。

• 「新しいプロジェクトのスキャフォールディングを行って」
• 「Next.js アプリを作成して」
• 「FastAPI と React をセットアップして」
• 「コード品質を分析して」
• 「コードベースのセキュリティ問題を確認して」
• 「どのスタックを使うべき？」
• 「フルスタックプロジェクトをセットアップして」
• 「プロジェクトのボイラープレートを生成して」

---

ツール

意思決定エンジン

決定論的なプロファイル選択ツールです。4 つの前提条件（チーム規模、リリース頻度、ユーザー向けかどうか、予算）と、任意のトラフィック／機密性に関する入力に基づいて、組み込みの 4 つのプロファイルを順位付けし、一致したプロファイルと SLO の下限、指名された承認者の承認経路を返します。必須の 4 つの入力なしでは、プロファイルの推奨を行いません。

使用方法：

# See all options
python scripts/fullstack_decision_engine.py --help

# Run against a sample input
python scripts/fullstack_decision_engine.py --sample

# Pick a profile from real inputs
python scripts/fullstack_decision_engine.py \
    --team-size-12mo 8 --cadence daily --user-facing true --budget 5000 \
    --traffic-p99-rps 50 --data-sensitivity pii-only

# JSON output for downstream tools
python scripts/fullstack_decision_engine.py --sample --output json

戻り値：一致したプロファイル名、スコア、一致／違反した制約、スタックの推奨、推奨しない選択肢、SLO の下限、指名された承認者の承認経路、正規リファレンスです。

このエンジンには、対話形式のヒアリングで確認するものと同じマトリックスが組み込まれています。入力がすでにわかっている場合は直接使用し、質問ごとにヒアリングする場合は cs-fullstack-engineer エージェント経由で使用してください。

---

プロジェクトスキャフォールダー

ボイラープレートコードを含むフルスタックプロジェクト構成を生成します。

対応テンプレート：

• nextjs - App Router、TypeScript、Tailwind CSS を使用する Next.js 14 以降
• fastapi-react - FastAPI バックエンド + React フロントエンド + PostgreSQL
• mern - TypeScript を使用する MongoDB、Express、React、Node.js
• django-react - Django REST Framework + React フロントエンド

使用方法：

# List available templates
python scripts/project_scaffolder.py --list-templates

# Create Next.js project
python scripts/project_scaffolder.py nextjs my-app

# Create FastAPI + React project
python scripts/project_scaffolder.py fastapi-react my-api

# Create MERN stack project
python scripts/project_scaffolder.py mern my-project

# Create Django + React project
python scripts/project_scaffolder.py django-react my-app

# Specify output directory
python scripts/project_scaffolder.py nextjs my-app --output ./projects

# JSON output
python scripts/project_scaffolder.py nextjs my-app --json

パラメーター：

パラメーター	説明
template	テンプレート名（nextjs、fastapi-react、mern、django-react）
project_name	新しいプロジェクトディレクトリの名前
--output, -o	出力ディレクトリ（デフォルト：現在のディレクトリ）
--list-templates, -l	使用可能なすべてのテンプレートを一覧表示
--json	JSON 形式で出力

出力内容：

• 必要なすべてのファイルを含むプロジェクト構成
• パッケージ設定（package.json、requirements.txt）
• TypeScript の設定
• Docker と docker-compose のセットアップ
• 環境ファイルのテンプレート
• プロジェクトを実行するための次の手順

---

コード品質アナライザー

フルスタックのコードベースを分析し、品質上の問題を検出します。

分析カテゴリ：

• セキュリティの脆弱性（ハードコードされたシークレット、インジェクションのリスク）
• コード複雑度の指標（循環的複雑度、ネストの深さ）
• 依存関係の健全性（古いパッケージ、既知の CVE）
• テストカバレッジの推定
• ドキュメントの品質

使用方法：

# Analyze current directory
python scripts/code_quality_analyzer.py .

# Analyze specific project
python scripts/code_quality_analyzer.py /path/to/project

# Verbose output with detailed findings
python scripts/code_quality_analyzer.py . --verbose

# JSON output
python scripts/code_quality_analyzer.py . --json

# Save report to file
python scripts/code_quality_analyzer.py . --output report.json

パラメーター：

パラメーター	説明
project_path	プロジェクトディレクトリへのパス（デフォルト：現在のディレクトリ）
--verbose, -v	詳細な検出結果を表示
--json	JSON 形式で出力
--output, -o	レポートをファイルに書き込む

出力内容：

• 全体スコア（0～100）とレターグレード
• 重大度別のセキュリティ問題（クリティカル、高、中、低）
• 複雑度の高いファイル
• CVE リファレンス付きの脆弱な依存関係
• テストカバレッジの推定
• ドキュメントの網羅性
• 優先順位付けされた推奨事項

出力例：

============================================================
CODE QUALITY ANALYSIS REPORT
============================================================

Overall Score: 75/100 (Grade: C)
Files Analyzed: 45
Total Lines: 12,500

--- SECURITY ---
  Critical: 1
  High: 2
  Medium: 5

--- COMPLEXITY ---
  Average Complexity: 8.5
  High Complexity Files: 3

--- RECOMMENDATIONS ---
1. [P0] SECURITY
   Issue: Potential hardcoded secret detected
   Action: Remove or secure sensitive data at line 42

---

ワークフロー

ワークフロー 1：新しいプロジェクトを開始する

1. 要件に基づいて適切なスタックを選択します（スタック決定マトリックスを参照）
2. プロジェクト構成をスキャフォールディングします
3. スキャフォールドを確認します。package.json（または requirements.txt）が存在することを確認します
4. 初回の品質チェックを実行します。続行する前に、P0 の問題に対処します
5. 開発環境をセットアップします

# 1. Scaffold project
python scripts/project_scaffolder.py nextjs my-saas-app

# 2. Verify scaffold succeeded
ls my-saas-app/package.json

# 3. Navigate and install
cd my-saas-app
npm install

# 4. Configure environment
cp .env.example .env.local

# 5. Run quality check
python scripts/code_quality_analyzer.py .

# 6. Start development
npm run dev

ワークフロー 2：既存のコードベースを監査する

1. コード品質分析を実行します
2. セキュリティの検出結果を確認します。P0（クリティカル）の問題はすべて直ちに修正します
3. アナライザーを再実行して、P0 の問題が解決されたことを確認します
4. P1／P2 の問題についてチケットを作成します

# 1. Full analysis
python scripts/code_quality_analyzer.py /path/to/project --verbose

# 2. Generate detailed report
python scripts/code_quality_analyzer.py /path/to/project --json --output audit.json

# 3. After fixing P0 issues, re-run to verify
python scripts/code_quality_analyzer.py /path/to/project --verbose

ワークフロー 3：スタックの選定

技術スタックガイドを使って選択肢を評価します。

1. SEO が必要ですか？ → SSR を使用する Next.js
2. API 中心のバックエンドですか？ → FastAPI または NestJS を分離して使用
3. リアルタイム機能が必要ですか？ → WebSocket レイヤーを追加
4. チームの専門知識 → チームのスキルに合わせてスタックを選択

詳細な比較については、references/tech_stack_guide.md をご覧ください。

---

リファレンスガイド

アーキテクチャパターン（references/architecture_patterns.md）

• フロントエンドのコンポーネントアーキテクチャ（アトミックデザイン、コンテナー／プレゼンテーショナル）
• バックエンドのパターン（クリーンアーキテクチャ、リポジトリパターン）
• API 設計（REST の規約、GraphQL スキーマ設計）
• データベースのパターン（コネクションプーリング、トランザクション、読み取りレプリカ）
• キャッシュ戦略（キャッシュアサイド、HTTP キャッシュヘッダー）
• 認証アーキテクチャ（JWT + リフレッシュトークン、セッション）

開発ワークフロー（references/development_workflows.md）

• ローカル開発環境のセットアップ（Docker Compose、環境設定）
• Git ワークフロー（トランクベース、Conventional Commits）
• CI/CD パイプライン（GitHub Actions の例）
• テスト戦略（ユニット、統合、E2E）
• コードレビューのプロセス（PR テンプレート、チェックリスト）
• デプロイ戦略（ブルーグリーン、カナリア、フィーチャーフラグ）
• モニタリングとオブザーバビリティ（ログ、メトリクス、ヘルスチェック）

技術スタックガイド（references/tech_stack_guide.md）

• フロントエンドフレームワークの比較（Next.js、React+Vite、Vue）
• バックエンドフレームワーク（Express、Fastify、NestJS、FastAPI、Django）
• データベースの選定（PostgreSQL、MongoDB、Redis）
• ORM（Prisma、Drizzle、SQLAlchemy）
• 認証ソリューション（Auth.js、Clerk、カスタム JWT）
• デプロイプラットフォーム（Vercel、Railway、AWS）
• ユースケース別のスタック推奨（MVP、SaaS、エンタープライズ）

---

クイックリファレンス

スタック選定マトリクス

要件	推奨
SEO が重要なサイト	SSR を使用する Next.js
社内ダッシュボード	React + Vite
API ファーストのバックエンド	FastAPI または Fastify
エンタープライズ規模	NestJS + PostgreSQL
迅速なプロトタイプ	Next.js API routes
ドキュメント中心のデータ	MongoDB
複雑なクエリ	PostgreSQL

よくある問題

問題	解決策
N+1 クエリ	DataLoader または Eager Loading を使用
ビルドが遅い	バンドルサイズを確認し、遅延読み込みを使用
認証の複雑さ	Auth.js または Clerk を使用
型エラー	tsconfig で strict mode を有効化
CORS の問題	ミドルウェアを適切に設定

---

前提条件と検証可能な成功基準（Karpathy の規律）

このスキルがコードの足場を作成、推奨、または変更する前に、以下の4つの前提条件を必ず明示する必要があります。不明な項目がある場合、このスキルは停止し、代わりに強制質問ライブラリに沿って進めます。

1. 現在のチーム規模 + 12か月後の人員数 — アーキテクチャ（モノリス／モジュラー／サービス）を決定します。Sam Newman：「MonolithFirst」。
2. 目標とするデプロイ頻度 — CI/CD への投資とフィーチャーフラグへの投資を決定します。Accelerate（Forsgren ほか、2018年）。
3. ユーザー向けか、社内向けか、マーケティングサイトか — スタックの選定とアクセシビリティ／パフォーマンスの予算を決定します。
4. 月額クラウド + SaaS 予算の上限 — 自社構築とマネージドサービスの使い分けを決定します。

検証可能な成功基準（Karpathy #4）— このスキルが出すすべての推奨には、機械で確認できる数値を3つ含める必要があります。

• API レイテンシの目標値（p50、p95、p99、単位：ms）
• フロントエンドのパフォーマンス目標値（モバイル 4G での LCP、INP、CLS）
• アップタイム／SLO の目標値

この3項目のいずれかが示されていない場合、その推奨は不完全です。強制質問ライブラリの Q7 に戻ってください。

scripts/fullstack_decision_engine.py ツールはこれらのチェックを実装しています。4つの前提条件すべてが入力されていないプロフィールの推奨を拒否し、一致したプロフィールの検証可能なしきい値を出力します。

---

カスタマイズプロファイル

profiles/ にある4つの組み込みプロファイルが、すべての推奨事項を調整します。

プロファイル	選択する状況	クラウドの上限	パターン
saas-startup	エンジニア10人未満、顧客向け、毎日以上の頻度でリリース	$8K/mo	Next.js + Postgres のモジュラーモノリス
enterprise-scale	エンジニア50人以上、規制対象、ゲート付きのPRごとのリリース	$250K/mo	ドメイン境界で分割されたサービス + プラットフォームチーム
internal-tool	エンジニア5人以下、認証で保護、DAU 100人未満	$500/mo	Retool を優先し、やむを得ない場合のみ薄いカスタムスタック
marketing-site	SEOに依存、書き込みはほぼゼロ	$200/mo	静的サイトを優先（Astro / 11ty / Next-static）

プロファイルを選択するには、次のようにします。

python scripts/fullstack_decision_engine.py \
  --team-size 6 --team-size-12mo 12 \
  --cadence daily --user-facing true --budget 5000 \
  --traffic-p99-rps 45 --data-sensitivity pii-only

このツールは、最適なプロファイル、次点の候補との差（15％以内の場合）、スタックの推奨事項、そのプロファイルで避けるべきアンチパターン、指名された承認者の承認フローを返します。このツールが自動承認することはありません。

カスタムプロファイルを追加するには、profiles/saas-startup.json を profiles/<your-org>.json にコピーし、constraints と stack_recommendations のブロックを調整して、再実行します。カスタマイズはJSONで行うため、コードの変更は必要ありません。

---

構成マップ

このスキルは、POWERFUL層の専門スキルが担当する範囲を再実装せず、それらに分岐します。完全なルーティング表については references/composition_map.md を参照してください。主な分岐先は次のとおりです。

対象	分岐先
APIコントラクトのレビュー	engineering/skills/api-design-reviewer/
データベーススキーマ設計	engineering/skills/database-designer/
信頼性 / SLO設計	engineering/slo-architect/
CI/CDパイプライン	engineering/skills/ci-cd-pipeline-builder/
パフォーマンスプロファイリング	engineering/skills/performance-profiler/
コミット前のKarpathyレビュー	engineering/karpathy-coder/
事前のアーキテクチャ徹底検討	engineering/grill-me/

cs-fullstack-engineer エージェント（agents/engineering/cs-fullstack-engineer.md 内）が、context: fork を使ってこれらの分岐を調整します。別のエージェントからは Agent({subagent_type: "cs-fullstack-engineer", prompt: "..."}) を使って呼び出すか、スラッシュコマンド /cs-fullstack-review <your problem> を使ってください。

---

追及質問ライブラリ（Matt Pocock grill）

アーキテクチャやスタックの決定を確定する前に、references/forcing_questions.md にある7つの追及質問を順に確認してください。それぞれに推奨回答、根拠となる規範の引用、却下基準があります。進め方は次のとおりです。

1. 1回につき質問は1つです。まとめて質問しないでください。
2. 常に根拠となる規範を引用し、回答を推奨してください。
3. 作業ファイル（例：/tmp/fullstack-grill-<date>.md）に回答を記録してください。
4. 却下基準に該当したら、そこで停止してください。未解決の問題を残したまま、周辺を足場固めしないでください。
5. Q7の後、7つの回答を入力として fullstack_decision_engine.py を実行してください。

7つの質問の概要（全文は参照ファイルに記載されています）：

1. 現在のチーム規模と、12か月後の人員数は？
2. デプロイ頻度は、PRごと、毎日、毎週、四半期ごとのどれですか？
3. 顧客向け、社内ツール、マーケティングサイトのどれですか？
4. 1年後のトラフィック予測（p50 / p99）は？
5. スタックに合わせて採用しますか、それともチームをトレーニングしますか？
6. 1年目の月間クラウド + SaaS費用の上限はいくらですか？
7. 数値目標を含む、検証可能な成功基準を3つ挙げてください。

---

他のエージェントやスキルからの呼び出し

このスキルは、次の3つの方法で他のエージェントやスキルから呼び出せます。

1. スラッシュコマンド： /cs-fullstack-review <prompt> — 完全な追及質問、意思決定エンジン、構成ルーティングを実行します。
2. エージェントのサブエージェント： Agent({subagent_type: "cs-fullstack-engineer", prompt: "..."}) — コンテキストを分岐し、200語以内の要約を返します。
3. ツールを直接呼び出す： python scripts/fullstack_decision_engine.py ... — 対話形式の追及質問を行わず、決定論的にプロファイルを照合します（入力がすでに分かっている場合に使用してください）。

呼び出しの完全な仕様については、agents/engineering/cs-fullstack-engineer.md を参照してください。