From bc009cffda4cc3afa1fe551d5e9b375a6605a0ea Mon Sep 17 00:00:00 2001 From: xiaomai Date: Fri, 8 May 2026 16:04:17 +0800 Subject: [PATCH] docs: add AGENTS.md documentation Create AGENTS.md to document agent-related information and guidelines --- AGENTS.md | 34 ++++++++++++++++++++++++++++++++++ 1 file changed, 34 insertions(+) create mode 100644 AGENTS.md diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..f141c38 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,34 @@ +# Repository Guidelines + +## Project Structure & Module Organization + +This is a Nuxt 4 dinner ticket system using Vue, Nitro, PostgreSQL, Redis, Tailwind CSS, and Nuxt UI. Frontend code lives under `app/`: pages, components, layouts, composables, middleware, and global styles. Server code lives under `server/`: API handlers in `server/api`, startup plugins in `server/plugins`, and database/auth/session helpers in `server/utils`. Shared TypeScript helpers live in `shared/`; static assets in `public/`. + +## Build, Test, and Development Commands + +- `pnpm install`: install dependencies using the pinned pnpm version. +- `pnpm dev`: start the Nuxt development server. +- `pnpm build`: build the production Nitro app. +- `pnpm preview` or `pnpm start`: preview or run the built app. +- `docker compose up --build`: start the app with PostgreSQL and Redis. +- `docker compose -f docker-compose.yml -f docker-compose.dev.yml up --build`: run the Docker hot-reload stack. + +## Coding Style & Naming Conventions + +Use TypeScript, Vue single-file components, and existing Nuxt conventions. Match the current style: 2-space indentation, single quotes, no semicolons, and explicit helpers. Name Nitro handlers by route and method, such as `server/api/bookings.get.ts` or `server/api/public/bookings/[token]/confirm.post.ts`. Keep server-only logic in `server/utils`, browser-facing logic in `app/composables`, and shared validation or formatting in `shared/`. Prefer Nuxt UI and Tailwind utilities over custom CSS unless styling is global. + +## Testing Guidelines + +No dedicated unit test framework is configured yet. `pnpm build` is the current verification gate, but agents should not run tests or builds in WSL unless explicitly asked; the maintainer will run them and report failures. For PostgreSQL, Redis, sessions, WebAuthn, or WhatsApp changes, verify with Docker and `GET /api/health`. If tests are added later, place them near the covered feature and document the command. + +## Commit & Pull Request Guidelines + +The Git history follows Conventional Commit-style messages, commonly `feat(scope): summary`, `fix(scope): summary`, `refactor(scope): summary`, and `build: summary`. Use scopes like `bookings`, `auth`, `users`, `i18n`, or `receipt`. Pull requests should include a concise description, verification steps, linked issues when applicable, and screenshots for UI changes. Note required `.env` changes, migrations, or Docker impacts. + +## Security & Configuration Tips + +Create local configuration from `.env.example`. Do not commit secrets, session keys, database URLs with credentials, or WhatsApp tokens. Keep `NUXT_PUBLIC_APP_URL` aligned with the browser origin because WebAuthn requires a stable relying-party origin. + +## Agent-Specific Instructions + +Keep implementations concise and scoped to the requested behavior. Prefer the smallest code change that fits existing patterns, and avoid unrelated refactors, formatting churn, or broad rewrites.