AIエージェントのコード品質を劇的に高める「Skills」実践ガイド：React & FastAPI編

---
name: react-architect
description: Use when creating new React components, refactoring UI code, or fixing styling issues.
---

# React Component Architecture

You are the Lead Frontend Architect. Adhere strictly to these rules when touching any `.tsx` file.

## 1. Structure Rules
- **Named Exports Only**: Never use default exports.
  - ✅ `export const Button = ...`
  - ❌ `export default function Button...`
- **Interface Definition**: Define a generic `Props` interface immediately before the component.
- **Top-Level Hooks**: All `useState`, `useEffect`, and custom hooks must be at the very top of the component body.

## 2. Logic & View Separation
- **No Complex Logic in JSX**: If a conditional or mapping logic takes more than 3 lines, extract it to a variable or helper function inside the component.
- **Custom Hooks**: If `useEffect` is complex (>5 lines), extract it to a custom hook immediately.

## 3. Styling Standards
- **Tailwind CSS**: Use utility classes.
- **Dynamic Classes**: ALWAYS use `clsx` or `tailwind-merge` for conditional classes.
  - ✅ `className={clsx("p-4", isActive && "bg-blue-500")}`
  - ❌ `className={"p-4 " + (isActive ? "bg-blue-500" : "")}`

## 4. Accessibility (a11y)
- **Interactive Elements**: Buttons and Links MUST have an `aria-label` if they contain only icons.

// ❌ 悪い例：型定義が雑、インラインスタイル、クラス名の条件分岐が読みにくい
import React, { useState } from 'react'

export default function UserCard({ user }) {
  const [open, setOpen] = useState(false)

  return (
    <div className={'card ' + (open ? 'active' : '')} style={{ padding: '20px' }}>
      <h3>{user.name}</h3>
      <button onClick={() => setOpen(!open)}>Toggle</button>
      {open && <div>{user.bio}</div>}
    </div>
  )
}

// ✅ 良い例：Named Export、明示的な型定義、clsxの使用、a11y配慮
import { useState } from 'react'
import { clsx } from 'clsx'

interface UserCardProps {
  user: {
    name: string
    bio: string
  }
}

export const UserCard = ({ user }: UserCardProps) => {
  const [isOpen, setIsOpen] = useState(false)

  const toggleOpen = () => setIsOpen((prev) => !prev)

  return (
    <div
      className={clsx(
        'p-5 rounded-lg border border-gray-200 transition-all',
        isOpen ? 'bg-blue-50 border-blue-500 shadow-md' : 'bg-white'
      )}
    >
      <h3 className="text-lg font-bold text-gray-900">{user.name}</h3>

      <button
        onClick={toggleOpen}
        className="mt-2 px-4 py-2 text-sm bg-gray-100 hover:bg-gray-200 rounded"
        aria-label={isOpen ? 'Hide details' : 'Show details'}
      >
        {isOpen ? 'Hide' : 'Show'} Details
      </button>

      {isOpen && <div className="mt-4 text-gray-700 leading-relaxed">{user.bio}</div>}
    </div>
  )
}

---
name: fastapi-master
description: Use when creating new API endpoints, modifying routes, or working on backend services in FastAPI.
---

# FastAPI Route Master Standards

Ensure all backend code complies with strictly typed, secure API patterns.

## 1. Schema First Development
- **No Dicts in Routes**: NEVER return a raw `dict` or accept raw arguments.
- **Pydantic Models**:
  - Define all Request/Response models in `src/schemas/`.
  - Use Pydantic v2 `BaseModel`.
  - Always set `ConfigDict(from_attributes=True)` for ORM compatibility.

## 2. Route Definition Rules
- **Explicit Response Model**: Every `@router` decorator MUST have `response_model` defined.
- **Status Codes**: Explicitly define `status_code` for creation (201) and deletion (204).
- **Dependency Injection**:
  - Use `Depends(get_db)` for database sessions.
  - Use `Depends(get_current_user)` for protected routes.

## 3. Error Handling Protocol
- **No Bare Excepts**: Never use `except: pass`.
- **HTTPExceptions**: Use `raise HTTPException(status_code=..., detail=...)` for logic errors.
- **404 Handling**: Always check if a resource exists before operating on it.

## 4. Service Layer Separation
- **Thin Routes**: Route functions should only handle HTTP concerns (params, status).
- **Fat Services**: Move business logic and DB queries to `src/crud/` or `src/services/`.

# ❌ IMPLICIT: 辞書を返し、エラー処理もない危険なコード
@app.post("/users")
def create_user(item: dict, db = Depends(get_db)):
    user = db.query(User).filter(User.email == item['email']).first()
    if user:
        return {"error": "exists"} # ステータスコードが200になってしまう！

    new_user = User(email=item['email'], password=item['password'])
    db.add(new_user)
    db.commit()
    return new_user # JSONへのシリアライズが不安定

# ✅ EXPLICIT: 型安全、適切なステータスコード、明確な責務分離
from fastapi import APIRouter, Depends, HTTPException, status
from sqlalchemy.orm import Session
from src import schemas, crud
from src.deps import get_db

router = APIRouter()

@router.post(
    "/users",
    response_model=schemas.UserResponse,
    status_code=status.HTTP_201_CREATED,
    summary="Create a new user"
)
def create_user(
    user_in: schemas.UserCreate,
    db: Session = Depends(get_db)
):
    # 1. Check constraints
    db_user = crud.get_user_by_email(db, email=user_in.email)
    if db_user:
        raise HTTPException(
            status_code=status.HTTP_400_BAD_REQUEST,
            detail="Email already registered"
        )

    # 2. Delegate creation to CRUD layer
    return crud.create_user(db=db, user=user_in)