# Implement

> Implements use cases and fixes bugs by creating Next.js pages, components, API route handlers, and server actions. Use when the user asks to "implement a use case", "fix a bug", "build the UI", "create an API endpoint", "write a page", or mentions Next.js implementation, App Router, server actions, or full-stack implementation.

- Skill: `nexadevapp/implement-2` (Agent Skill)
- Install (CLI): `npx skillmds@latest add nexadevapp/implement-2`
- Raw SKILL.md: https://api.skillmd.com/api/skills/nexadevapp/implement-2/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Web & Frontend
- Author: nexadevapp (https://skillmd.com/u/nexadevapp)
- Updated: 2026-09-21
- Page: https://skillmd.com/skills/nexadevapp/implement-2

---


# Implement Use Case

## Instructions

Implement $ARGUMENTS using Next.js App Router for both the UI and API layer.
$ARGUMENTS can be a use case (`UC-XXX`), a technical task (`TT-XXX`), or a bug fix (`BUG-XXX`).
Write unit tests alongside the implementation. Integration tests (`vitest-test`) and e2e tests (`playwright-test`) are separate skills.

Use the context7 MCP server to look up Next.js documentation when needed.

## DO NOT

- Create integration or e2e tests (use dedicated testing skills instead)
- Use the Pages Router (use App Router exclusively)
- Use raw SQL queries (use Prisma Client)
- Use client components when server components suffice
- Put database calls in client components or API routes called only by server components
- Make implementation decisions without documenting their provenance (EXPLICIT vs INFERRED)
- Over-engineer — implement only what the specification requires. No speculative abstractions, unnecessary indirection, premature generalisation, or features not in the spec. Three similar lines of code are better than a premature abstraction. If a simple approach satisfies the requirement, use it.

## Nexa Rules Gate

Read and follow `${CLAUDE_PLUGIN_ROOT}/shared/readiness/NEXA_RULES_GATE.md`.

## Worktree Gate

Read and follow `${CLAUDE_PLUGIN_ROOT}/shared/readiness/WORKTREE_GATE.md`.

## Project Readiness Gate

Read and follow `${CLAUDE_PLUGIN_ROOT}/shared/readiness/PROJECT_READINESS.md`.

This gate checks that cross-cutting infrastructure (middleware, error logging, security headers,
environment configuration) exists before use case implementation begins. It applies to `UC-XXX`
items only — `TT-XXX` and `BUG-XXX` items skip this gate.

Do not proceed with implementation until all items pass or the user explicitly waives failures.

## DoR Check

- For **UC-XXX**: Read and follow `${CLAUDE_PLUGIN_ROOT}/shared/readiness/DEFINITION_OF_READY.md`.
- For **TT-XXX**: Read and follow `${CLAUDE_PLUGIN_ROOT}/shared/readiness/DEFINITION_OF_READY_TT.md`.
- For **BUG-XXX**: Read and follow `${CLAUDE_PLUGIN_ROOT}/shared/readiness/DEFINITION_OF_READY_BUG.md`.

Do not proceed with implementation until all items pass or the user explicitly waives failures.

## Tracking

Read and follow the **Before Implementation** steps in `${CLAUDE_PLUGIN_ROOT}/shared/tracking/TRACKING.md`.

## Test Data Conventions

- Use only `example.com` for test emails and accounts (e.g., `user@example.com`, `admin@example.com`). This is an IANA-reserved domain that will never route real mail.

## Workflow

1. Read the specification:
    - For **UC-XXX**: Read the use case specification from `docs/use_cases/`
    - For **TT-XXX**: Read the technical task specification from `docs/technical_tasks/`
    - For **BUG-XXX**: Read the bug report from `docs/bugs/`
2. Read the entity model from `docs/entity_model.md` (if applicable)
3. Read the design artifact from `docs/designs/` (if it exists for this UC). When a design artifact exists, the implementation must match the specified screens, layout, components, states, and navigation flow.
4. Read project design rules from `docs/designs/DESIGN_RULES.md` (if it exists). These are project-specific constraints — e.g., shared layout elements (header, footer, sidebar), mandatory components, or navigation patterns — that every implementation must follow. Missing a shared element specified in design rules is a defect.
5. Check existing code for patterns and conventions
6. **i18n Detection** — Always check whether the project uses internationalization.
   First, check the project's `CLAUDE.md` for the marker `<!-- NEXA_I18N_CONFIGURED -->`.
   If absent, fall back to looking for i18n indicators: translation/message files, i18n
   configuration, locale directories, translation function imports (`useTranslations`,
   `getTranslations`, `t()`, `intl`, etc.), locale-based routing segments (`[locale]`,
   `[lang]`), or i18n libraries in `package.json` (e.g., `next-intl`, `react-intl`,
   `react-i18next`, `i18next`).
   If any i18n setup is found, **all user-facing strings in this implementation MUST use the
   project's established translation pattern**:
    - Study how existing pages use translations and follow the same pattern
    - For every new page or section, add translation keys to **all** locale files following
      the project's existing file structure and naming conventions
    - User-facing error messages in server actions and API route handlers must also use
      translation keys, not hardcoded strings
    - Use the project's localized navigation utilities if they exist, instead of raw framework imports
    - Place new pages under the locale route segment if the project uses locale-based routing
7. Implement API route handlers (if needed for client-side fetching):
    - Create route handlers in `app/api/**/route.ts`
    - Export named functions matching HTTP methods (`GET`, `POST`, `PUT`, `DELETE`)
    - Validate request bodies with zod
    - Use Prisma Client for data access
    - Return `NextResponse.json()` with appropriate status codes
8. Implement server actions (if needed for form mutations):
    - Create actions in `app/actions/` or colocate with the page
    - Mark with `"use server"` directive
    - Validate input with zod
    - Use Prisma Client for data access
    - Call `revalidatePath()` or `revalidateTag()` for cache invalidation
9. Implement the UI:
    - Create or update `page.tsx` and `layout.tsx` files
    - Use server components by default for data fetching with Prisma
    - Use client components (`"use client"`) only for interactivity (forms, event handlers, state)
    - Create reusable UI components in `components/`
    - Handle loading states with `loading.tsx`
    - Handle errors with `error.tsx`
    - Handle empty states
    - When a design artifact exists, match the specified layout, components, states, and navigation
    - When project design rules exist (read in step 4), enforce every rule — e.g., include shared layout elements, follow mandatory navigation patterns, and apply required brand guidelines
    - When i18n is active (detected in step 6), every user-facing string must use the project's translation pattern — no hardcoded text in JSX
    - When implementing forms where users enter data, always add client-side and server-side validation:
        - Define a zod schema for each form's input fields
        - Apply client-side validation to show inline field errors before submission
        - Validate again on the server side in the server action or API route handler (never trust client-only validation)
        - Display server-side validation errors back to the user
10. Write unit tests for the implemented logic:
    - Test API route handlers with mocked Prisma Client
    - Test server actions with mocked dependencies
    - Test client components with React Testing Library
    - When forms are involved, write dedicated validation unit tests:
        - Test the zod schema directly: valid inputs pass, invalid inputs produce the expected errors
        - Test that server actions and API route handlers reject invalid input and return appropriate error responses
        - Test that form components display validation errors for invalid input
    - Run tests with `npx vitest run` to verify they pass
11. Run the `/code-quality` skill
12. Verify the implementation compiles successfully with `next build`
13. Document implementation decisions in a `DECISIONS.md` file (or in the PR description):
    - For each non-trivial decision made during implementation, record:
      - **Decision:** What was decided
      - **Provenance:** EXPLICIT (from spec/requirements) or INFERRED (agent reasoning)
      - **Source/Reasoning:** Quote the source document or explain the reasoning
    - INFERRED decisions are candidates for stakeholder review before merge

## Post-Implementation Tracking

Read and follow the **After Implementation** steps in `${CLAUDE_PLUGIN_ROOT}/shared/tracking/TRACKING.md`.

## Resources

- Use the context7 MCP server for Next.js documentation