陌讯skills聚合平台

sasatech-next-architecture

📁 sasatech-labs/skills 📅 Jan 24, 2026
15
总安装量
10
周安装量
#22386
全站排名
安装命令
npx skills add https://github.com/sasatech-labs/skills --skill sasatech-next-architecture

Agent 安装分布

claude-code 8
cursor 5
antigravity 4
opencode 3
codex 3

Skill 文档

SasaTech Architecture

アーキテクチャ概要

Feature-based Layer Architecture for Next.js (App Router + Supabase)

レイヤー構成

Handler                 リクエスト/レスポンス、バリデーション、認証
        ↓
Service                 ビジネスロジック、複数 Repository 連携
        ↓
Repository              データアクセス
Adapter                 外部 API 連携（Stripe, Resend 等）

ディレクトリ構成

src/
├── app/                      # Next.js App Router
│   ├── (auth)/               # 認証が必要なルートグループ
│   ├── (public)/             # 公開ルートグループ
│   └── api/                  # API Routes (薄いエントリーポイント)
│
├── features/                 # 機能単位のモジュール
│   └── [feature]/
│       ├── index.ts          # 公開API
│       └── core/
│           ├── schema.ts     # Zodスキーマ + 型定義
│           ├── handler.ts    # リクエスト / レスポンス処理 (server-only)
│           ├── service.ts    # ビジネスロジック (server-only)
│           ├── repository.ts # データアクセス (server-only)
│           ├── adapter.ts    # 外部API連携 (server-only)
│           ├── fetcher.ts    # API呼び出し
│           └── hooks.ts      # SWR Hook等
│
├── components/               # 共通UIコンポーネント
├── hooks/                    # 共通Hooks
├── lib/                      # ユーティリティ
│   └── adapters/             # 外部サービス連携
└── types/                    # 共通型定義、Supabase生成型

ガイドとルールの違い

このスキルは ガイド と ルール の2種類のドキュメントで構成されています。

項目 ガイド ルール
目的 アーキテクチャや実装パターンの理解を深める 守るべき制約を明確に定義する
内容 HOW / WHY — 設計思想、セットアップ手順、コード例 DO / DON’T — NG例とOK例による判定基準
形式 チュートリアル形式 メタデータ（impact, tags）付きの短いルール形式
読むタイミング プロジェクト参加時の学習、設計判断の参考 コード実装時の準拠確認、コードレビュー

ガイド

ガイド 説明
architecture.md Feature-based Layer Architecture の全体設計。レイヤー構成、責務分離、ディレクトリ構成
architecture/handler.md Handler層の実装。リクエスト処理、バリデーション、認証チェック、エラーハンドリング
architecture/service.md Service層の実装。ビジネスロジック、Repository/Adapter連携、トランザクション管理
architecture/repository.md Repository層の実装。データアクセスの抽象化、Supabaseクエリのカプセル化
architecture/adapter.md Adapter層の実装。外部サービス（決済、メール、AI等）との連携をカプセル化
testing.md レイヤーごとのテスト戦略。Unit / Integration テストの範囲とモック方針
database.md データベース設計。コメント規約、マイグレーション、Supabase との連携
logging.md pino を使用した構造化ログの実装。レイヤーごとのログ出力方針
setup.md 新規プロジェクトのセットアップ手順。依存パッケージ、基盤ファイルの配置

ルール

カテゴリ

カテゴリ Prefix
アーキテクチャ arch-
データ data-
サーバーサイド保護 server-
スキーマ・型定義 schema-
レスポンス response-
テスト test-
バリデーション validation-
命名規則 naming-
フロントエンド frontend-

インパクト

Impact は、違反時にアーキテクチャへ与える影響の深刻度で定義します。

Impact 基準
CRITICAL アーキテクチャの根幹が壊れる。違反するとこの設計パターン自体が成立しない
HIGH アーキテクチャの整合性や保守性を大きく損なう
MEDIUM コードの品質や一貫性を低下させる
LOW 開発体験やパターンの統一に関する推奨事項

アーキテクチャ (arch-)

ルール Impact 説明
arch-three-layers CRITICAL Handler → Service → Repository, Adapter の構成を必ず経由
arch-feature-structure CRITICAL 機能単位で features/ にモジュール化
arch-external-services HIGH Stripe, Resend 等の外部サービスは Adapter 経由
arch-logging-strategy MEDIUM pino で構造化ログ、console.log 禁止

データ (data-)

ルール Impact 説明
data-no-getall HIGH 全件取得禁止、MAX_LIMIT でサーバー側上限を強制
data-pagination HIGH リスト取得は必ずページネーション付きで総件数を返却
data-comment-required LOW テーブル・カラムに日本語コメント必須

サーバーサイド保護 (server-)

ルール Impact 説明
server-supabase-via-api CRITICAL クライアントから Supabase 直接使用禁止、API Route 経由必須
server-only-directive HIGH Service/Repository に import 'server-only' を必須で記述
server-no-public-env HIGH 機密情報（Supabase, API キー）に NEXT_PUBLIC_ 禁止

スキーマ・型定義 (schema-)

ルール Impact 説明
schema-single-source HIGH 型定義は schema.ts に一元化、分散禁止
schema-no-types-file MEDIUM Feature 内に types.ts 作成禁止
schema-zod-infer MEDIUM Input 型は手書きせず z.infer<typeof schema> で導出

レスポンス (response-)

ルール Impact 説明
response-apperror MEDIUM エラーは AppError クラスでスロー、生の Error 禁止
response-helpers LOW ok(), created(), notFound() 等のヘルパーを使用

テスト (test-)

ルール Impact 説明
test-layer-mocking HIGH 各レイヤーは直下の依存のみをモック
test-server-only MEDIUM server-only はテスト環境でモック必須
test-file-location LOW テストファイルは __tests__ に配置
test-naming LOW テストは日本語で意図を明確に

バリデーション (validation-)

ルール Impact 説明
validation-body MEDIUM POST/PATCH のリクエストボディは Zod でバリデーション
validation-params MEDIUM URL パラメータ（ID 等）も Zod でバリデーション

命名規則 (naming-)

ルール Impact 説明
naming-files LOW ファイル・ディレクトリ名は kebab-case（フレームワーク規約ファイルを除く）
naming-methods LOW Repository: findMany/findById、Service: get*/create*

フロントエンド (frontend-)

ルール Impact 説明
frontend-fetcher LOW Feature ごとに fetcher.ts を作成して API 呼び出しを集約
frontend-hooks LOW SWR を使用した Hook パターンでデータ取得
GitHub 仓库 ↗ ← 返回陌讯 Skills 聚合平台
本页面由 陌讯 Skills 聚合平台 收录整理，数据定期更新。