sasatech-next-architecture

by @sasatech-labs in Development

# Install this skill:

npx skills add sasatech-labs/skills --skill "sasatech-next-architecture"

Install specific skill from multi-skill repository

# Description

Next.js App Router architecture with Feature-based Layer Architecture pattern. Use when creating API routes, services, repositories, or components with Supabase and TypeScript. Covers Handler/Service/Repository, Adapter layers, Zod validation, and feature module structure.

# SKILL.md

name: sasatech-next-architecture
description: Next.js App Router architecture with Feature-based Layer Architecture pattern. Use when creating API routes, services, repositories, or components with Supabase and TypeScript. Covers Handler/Service/Repository, Adapter layers, Zod validation, and feature module structure.

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 パターンでデータ取得

# Supported AI Coding Agents

This skill is compatible with the SKILL.md standard and works with all major AI coding agents:

⚡ Amp 🚀 Antigravity 🤖 Claude Code 🦀 Clawdbot 📝 Codex ▶️ Cursor 🤖 Droid 💎 Gemini CLI 🐙 GitHub Copilot 🪿 Goose 📊 Kilo Code 🔧 Kiro CLI 💻 OpenCode 🦘 Roo Code 🌲 Trae 🏄 Windsurf

Learn more about the SKILL.md standard and how to use these skills with your preferred AI coding agent.

sasatech-next-architecture

# Description

# SKILL.md

SasaTech Architecture

アーキテクチャ概要

レイヤー構成

ディレクトリ構成

ガイドとルールの違い

ガイド

ルール

カテゴリ

インパクト

アーキテクチャ (arch-)

データ (data-)

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

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

レスポンス (response-)

テスト (test-)

バリデーション (validation-)

命名規則 (naming-)

フロントエンド (frontend-)

# Related Skills