AGENT SKILL

java-coding-standards

Spring Bootサービス向けのJavaコーディング標準:命名、不変性、Optional使用、ストリーム、例外、ジェネリクス、プロジェクトレイアウト。

License 许可
MIT
最近更新
2026-11-10
Stars
★ 1
Forks
0

01 前言 Front Matter

name
java-coding-standards
description
Spring Bootサービス向けのJavaコーディング標準:命名、不変性、Optional使用、ストリーム、例外、ジェネリクス、プロジェクトレイアウト。

03 SKILL.md 正文

Javaコーディング標準

Spring Bootサービスにおける読みやすく保守可能なJava(17+)コードの標準。

核となる原則

  • 巧妙さよりも明確さを優先
  • デフォルトで不変; 共有可変状態を最小化
  • 意味のある例外で早期失敗
  • 一貫した命名とパッケージ構造

命名

// PASS: クラス/レコード: PascalCase
public class MarketService {}
public record Money(BigDecimal amount, Currency currency) {}

// PASS: メソッド/フィールド: camelCase
private final MarketRepository marketRepository;
public Market findBySlug(String slug) {}

// PASS: 定数: UPPER_SNAKE_CASE
private static final int MAX_PAGE_SIZE = 100;

不変性

// PASS: recordとfinalフィールドを優先
public record MarketDto(Long id, String name, MarketStatus status) {}

public class Market {
  private final Long id;
  private final String name;
  // getterのみ、setterなし
}

Optionalの使用

// PASS: find*メソッドからOptionalを返す
Optional<Market> market = marketRepository.findBySlug(slug);

// PASS: get()の代わりにmap/flatMapを使用
return market
    .map(MarketResponse::from)
    .orElseThrow(() -> new EntityNotFoundException("Market not found"));

ストリームのベストプラクティス

// PASS: 変換にストリームを使用し、パイプラインを短く保つ
List<String> names = markets.stream()
    .map(Market::name)
    .filter(Objects::nonNull)
    .toList();

// FAIL: 複雑なネストされたストリームを避ける; 明確性のためにループを優先

例外

  • ドメインエラーには非チェック例外を使用; 技術的例外はコンテキストとともにラップ
  • ドメイン固有の例外を作成(例: MarketNotFoundException)
  • 広範なcatch (Exception ex)を避ける(中央でリスロー/ログ記録する場合を除く)
throw new MarketNotFoundException(slug);

ジェネリクスと型安全性

  • 生の型を避ける; ジェネリックパラメータを宣言
  • 再利用可能なユーティリティには境界付きジェネリクスを優先
public <T extends Identifiable> Map<Long, T> indexById(Collection<T> items) { ... }

プロジェクト構造(Maven/Gradle)

src/main/java/com/example/app/
  config/
  controller/
  service/
  repository/
  domain/
  dto/
  util/
src/main/resources/
  application.yml
src/test/java/... (mainをミラー)

フォーマットとスタイル

  • 一貫して2または4スペースを使用(プロジェクト標準)
  • ファイルごとに1つのpublicトップレベル型
  • メソッドを短く集中的に保つ; ヘルパーを抽出
  • メンバーの順序: 定数、フィールド、コンストラクタ、publicメソッド、protected、private

避けるべきコードの臭い

  • 長いパラメータリスト → DTO/ビルダーを使用
  • 深いネスト → 早期リターン
  • マジックナンバー → 名前付き定数
  • 静的可変状態 → 依存性注入を優先
  • サイレントなcatchブロック → ログを記録して行動、または再スロー

ログ記録

private static final Logger log = LoggerFactory.getLogger(MarketService.class);
log.info("fetch_market slug={}", slug);
log.error("failed_fetch_market slug={}", slug, ex);

Null処理

  • やむを得ない場合のみ@Nullableを受け入れる; それ以外は@NonNullを使用
  • 入力にBean Validation(@NotNull、@NotBlank)を使用

テストの期待

  • JUnit 5 + AssertJで流暢なアサーション
  • モック用のMockito; 可能な限り部分モックを避ける
  • 決定論的テストを優先; 隠れたsleepなし

覚えておく: コードを意図的、型付き、観察可能に保つ。必要性が証明されない限り、マイクロ最適化よりも保守性を最適化します。

04 同仓库更多 Skills

YYC-Cube
YYC-Cube/YYC3-Knowledge-Base

vercel-sandbox

Run agent-browser + Chrome inside Vercel Sandbox microVMs for browser automation from any Vercel-deployed app. Use when the user needs browser automation in a Vercel app (Next.js, SvelteKit, Nuxt, Remix, Astro, etc.), wants to run headless Chrome without binary size limits, needs persistent browser sessions across commands, or wants ephemeral isolated browser environments. Triggers include "Vercel Sandbox browser", "microVM Chrome", "agent-browser in sandbox", "browser automation on Vercel", or any task requiring Chrome in a Vercel Sandbox.

★ 1
YYC-Cube
YYC-Cube/YYC3-Knowledge-Base

slack

Interact with Slack workspaces using browser automation. Use when the user needs to check unread channels, navigate Slack, send messages, extract data, find information, search conversations, or automate any Slack task. Triggers include "check my Slack", "what channels have unreads", "send a message to", "search Slack for", "extract from Slack", "find who said", or any task requiring programmatic Slack interaction.

★ 1
YYC-Cube
YYC-Cube/YYC3-Knowledge-Base

electron

Automate Electron desktop apps (VS Code, Slack, Discord, Figma, Notion, Spotify, etc.) using agent-browser via Chrome DevTools Protocol. Use when the user needs to interact with an Electron app, automate a desktop app, connect to a running app, control a native app, or test an Electron application. Triggers include "automate Slack app", "control VS Code", "interact with Discord app", "test this Electron app", "connect to desktop app", or any task requiring automation of a native Electron application.

★ 1
YYC-Cube
YYC-Cube/YYC3-Knowledge-Base

dogfood

Systematically explore and test a web application to find bugs, UX issues, and other problems. Use when asked to "dogfood", "QA", "exploratory test", "find issues", "bug hunt", "test this app/site/platform", or review the quality of a web application. Produces a structured report with full reproduction evidence -- step-by-step screenshots, repro videos, and detailed repro steps for every issue -- so findings can be handed directly to the responsible teams.

★ 1
YYC-Cube
YYC-Cube/YYC3-Knowledge-Base

agent-browser

Browser automation CLI for AI agents. Use when the user needs to interact with websites, including navigating pages, filling forms, clicking buttons, taking screenshots, extracting data, testing web apps, or automating any browser task. Triggers include requests to "open a website", "fill out a form", "click a button", "take a screenshot", "scrape data from a page", "test this web app", "login to a site", "automate browser actions", or any task requiring programmatic web interaction.

★ 1
YYC-Cube
YYC-Cube/YYC3-Knowledge-Base

shadcn

Manages shadcn components and projects — adding, searching, fixing, debugging, styling, and composing UI, including chat interfaces. Provides project context, component docs, and usage examples. Applies when working with shadcn/ui, component registries, presets, --preset codes, or any project with a components.json file. Also triggers for "shadcn init", "create an app with --preset", "switch to --preset", and for building a design system or applying a DESIGN.md or brand spec to shadcn/ui.

★ 1