|
| 1 | +# Agent Operational Guide |
| 2 | + |
| 3 | +This document provides instructions and standards for AI agents operating within this codebase. |
| 4 | + |
| 5 | +## 1. Project Overview |
| 6 | + |
| 7 | +- **Framework:** Next.js 16 (App Router) |
| 8 | +- **Language:** TypeScript |
| 9 | +- **Styling:** Tailwind CSS 4, Framer Motion, GSAP |
| 10 | +- **3D/Graphics:** Three.js, React Three Fiber, React Three Drei, Pixiv Three VRM |
| 11 | +- **Internationalization:** `next-intl` |
| 12 | +- **Package Manager:** npm (with `bun.lock` present) |
| 13 | + |
| 14 | +## 2. Build, Lint, and Test Commands |
| 15 | + |
| 16 | +### Build & Run |
| 17 | +Always use Bun to run scripts to ensure compatibility with the lockfile. |
| 18 | +- **Development Server:** `bun run dev` |
| 19 | +- **Production Build:** `bun run build` |
| 20 | +- **Start Production:** `bun run start` |
| 21 | + |
| 22 | +### Linting & Formatting |
| 23 | +This project uses **Biome** for formatting and linting, alongside Next.js's built-in linter. |
| 24 | +- **Format & Fix:** `bun run format` (Runs `biome format --write .`) |
| 25 | +- **Lint:** `bun run lint` (Runs `next lint`) |
| 26 | + |
| 27 | +**Note to Agents:** Always run `bun run format` after making changes to ensure code complies with project standards. |
| 28 | + |
| 29 | +### Testing |
| 30 | +- **Status:** No testing framework or test files were detected in the initial scan. |
| 31 | +- **Instruction:** If asked to write tests, verify if a framework (like Vitest or Jest) has been added since this file was created. If not, ask the user for their preference or propose installing **Vitest** for a modern, fast testing experience compatible with Next.js and Vite. |
| 32 | +- **Command (Placeholder):** `npm test` (if configured) |
| 33 | + |
| 34 | +## 3. Code Style & Conventions |
| 35 | + |
| 36 | +### General |
| 37 | +- **Structure:** Follow the Next.js App Router structure (`src/app`). |
| 38 | +- **Imports:** Use absolute imports with the `@/` alias (e.g., `import { Button } from "@/components/ui/button"`). |
| 39 | +- **Sorting:** Imports are sorted automatically by Biome. Run `npm run format` to enforce this. |
| 40 | + |
| 41 | +### TypeScript |
| 42 | +- **Strictness:** `tsconfig.json` has `"strict": false`. Be mindful of potential null/undefined values, but do not aggressively enforce strict null checks unless refactoring specific modules to be stricter. |
| 43 | +- **Types:** Prefer interfaces over types for object definitions. Explicitly type component props. |
| 44 | + |
| 45 | +### Naming |
| 46 | +- **Components:** PascalCase (e.g., `ContactPage`, `SubmitButton`). |
| 47 | +- **Files:** |
| 48 | + - Components: PascalCase (e.g., `Button.tsx`). |
| 49 | + - Utilities/Hooks: camelCase (e.g., `useWindowSize.ts`, `utils.ts`). |
| 50 | + - App Router: kebab-case/standard Next.js conventions (e.g., `page.tsx`, `layout.tsx`, `loading.tsx`). |
| 51 | + |
| 52 | +### Styling (Tailwind CSS & Components) |
| 53 | +- **Utility Classes:** Use Tailwind CSS classes for styling. |
| 54 | +- **Components:** |
| 55 | + - Use **Shadcn UI** components from `@/components/ui` when available. |
| 56 | + - Use **Animate UI** components from `@/components/animate-ui` for animations. |
| 57 | + - Use **Lucide React** for icons (`import { Mail } from "lucide-react"`). |
| 58 | +- **Icons:** Do **not** use `react-icons` if Lucide equivalents are available. |
| 59 | +- **Responsive Design:** Use Tailwind's md: class for styles for desktop views. Don't use any other responsive classes such as sm:, lg:, xl:, etc. |
| 60 | + |
| 61 | +### Internationalization (i18n) |
| 62 | +- Use `next-intl` for translations. |
| 63 | +- access translations via `const t = useTranslations("namespace")`. |
| 64 | +- keys should be kebab-case (e.g., `contact.general-support`). |
| 65 | + |
| 66 | +## 4. Error Handling |
| 67 | +- Use standard `try/catch` blocks for async operations. |
| 68 | +- Ensure user-facing errors are localized using `next-intl`. |
| 69 | +- For API routes, return standard HTTP status codes and JSON error responses. |
| 70 | + |
| 71 | +## 5. Agent Behavior |
| 72 | +- **Proactive Formatting:** Always format code before finishing a task. |
| 73 | +- **Safety:** Do not delete production configurations or large chunks of code without verification. |
| 74 | +- **Context:** Read `package.json` and `tsconfig.json` if you are unsure about dependencies or paths. |
| 75 | +- **Cleanliness:** No comments are required unless asked for by the user. Keep code clean and concise. |
| 76 | +- **Edits:** If a file has been edited since the last read, retain any new code or changes made by the user. |
| 77 | + |
0 commit comments