docs: expand project design and agent guidelines
Rewrite DESIGN.md to detail product goals, data models, and API boundaries Update AGENTS.md with existing UI patterns, i18n rules, and strict completion criteria
This commit is contained in:
158
AGENTS.md
158
AGENTS.md
@@ -6,6 +6,7 @@
|
||||
* Follow the existing structure and conventions strictly.
|
||||
* Make **minimal, targeted changes only**. Do not refactor unrelated code.
|
||||
* Prefer clarity over cleverness. Avoid unnecessary abstraction.
|
||||
* Keep `DESIGN.md` aligned with implemented product behavior when changing data models, APIs, routes, permissions, or user-facing workflows.
|
||||
|
||||
---
|
||||
|
||||
@@ -22,15 +23,91 @@ For any non-trivial task:
|
||||
|
||||
Do NOT skip planning.
|
||||
|
||||
For documentation-only tasks, still follow the planning workflow, but do not run unrelated builds or tests unless the document change depends on generated output.
|
||||
|
||||
---
|
||||
|
||||
## Project Context
|
||||
|
||||
* Goal: Pokopia Wiki, a community-editable game wiki.
|
||||
* Repository: pnpm workspace monorepo.
|
||||
* Runtime baseline: Node.js >= 22.
|
||||
* Frontend:
|
||||
|
||||
* Vue
|
||||
* Vite
|
||||
* Vue Router
|
||||
* Vue I18n
|
||||
* Iconify
|
||||
* TypeScript
|
||||
|
||||
* Backend:
|
||||
|
||||
* Node.js
|
||||
* Fastify
|
||||
* PostgreSQL
|
||||
* `pg`
|
||||
* TypeScript
|
||||
|
||||
* Infra:
|
||||
|
||||
* Docker
|
||||
* docker compose
|
||||
|
||||
---
|
||||
|
||||
## Existing Product Shape
|
||||
|
||||
* Public users can browse Wiki content.
|
||||
* Registered users must verify email before editing.
|
||||
* Verified users can edit Wiki content and management data; there is no separate role system currently.
|
||||
* Main public sections:
|
||||
|
||||
* Pokemon
|
||||
* Habitats
|
||||
* Items
|
||||
* Recipes
|
||||
* Daily CheckList
|
||||
|
||||
* Management covers:
|
||||
|
||||
* System config
|
||||
* Languages
|
||||
* Daily CheckList tasks
|
||||
* Sorting for Pokemon, items, recipes, and habitats
|
||||
|
||||
* Main entity create/edit flows use route-backed modal dialogs.
|
||||
* Internationalization is part of the product model, not just UI copy.
|
||||
* Detailed edit history and editor attribution are part of entity detail behavior.
|
||||
|
||||
---
|
||||
|
||||
## UI Design Guidelines
|
||||
|
||||
* Use `DesignGuidelines.html` as the reference for UI design, visual style, and component behavior.
|
||||
* Prefer reusing existing components that already match the guidelines.
|
||||
* Existing shared UI patterns include:
|
||||
|
||||
* `AppShell`
|
||||
* `PageHeader`
|
||||
* `Modal`
|
||||
* `FilterPanel`
|
||||
* `EntityCard`
|
||||
* `DetailSection`
|
||||
* `EditMeta`
|
||||
* `EditHistoryPanel`
|
||||
* `Skeleton`
|
||||
* `Tabs`
|
||||
* `SwitchGroup`
|
||||
* `TagsSelect`
|
||||
* `TranslationFields`
|
||||
* `ReorderableList`
|
||||
|
||||
* If a needed component does not exist, create the smallest necessary component based on `DesignGuidelines.html`.
|
||||
* Existing components may be upgraded to match `DesignGuidelines.html`, but only when directly related to the task.
|
||||
* Do not introduce broad UI rewrites, new design systems, or extra abstraction layers unless explicitly required.
|
||||
* Use Skeleton loaders for data loading states instead of user-facing loading remarks when the existing page pattern supports it.
|
||||
* Use icon-based navigation and actions consistently with the existing Iconify setup.
|
||||
|
||||
---
|
||||
|
||||
@@ -42,6 +119,8 @@ Do NOT skip planning.
|
||||
* Introduce new layers (services, utils, hooks, etc.) unless clearly required
|
||||
* Split files unnecessarily
|
||||
* Rewrite existing modules without explicit instruction
|
||||
* Change unrelated route, API, or schema behavior while working on UI-only tasks
|
||||
|
||||
* Prefer editing existing files over creating new ones.
|
||||
* Keep functions and components small and readable.
|
||||
|
||||
@@ -62,31 +141,52 @@ User-facing UI must NEVER contain:
|
||||
|
||||
### Strict Rules
|
||||
|
||||
* Only render **business data** and intended UI text
|
||||
* Only render **business data** and intended UI text.
|
||||
* Never display:
|
||||
|
||||
* "Updated successfully because..."
|
||||
* "Changed X to Y"
|
||||
* "TODO", "NOTE", "DEBUG"
|
||||
* Debug information must go to logs, not UI
|
||||
* Separate internal data from API responses
|
||||
|
||||
* Debug information must go to logs, not UI.
|
||||
* Separate internal data from API responses.
|
||||
* Do not expose raw database column names in user-facing labels unless `DESIGN.md` explicitly defines that label.
|
||||
|
||||
Violations are considered critical errors.
|
||||
|
||||
---
|
||||
|
||||
## Data & API Design Rules
|
||||
## Data, API, and i18n Rules
|
||||
|
||||
* Follow `DESIGN.md` as the **single source of truth**
|
||||
* Follow `DESIGN.md` as the **single source of truth**.
|
||||
* PostgreSQL:
|
||||
|
||||
* use `snake_case`
|
||||
* define proper primary/foreign keys
|
||||
* preserve existing audit columns on editable entities
|
||||
* preserve `sort_order` behavior for sortable lists
|
||||
* avoid premature optimization
|
||||
|
||||
* APIs:
|
||||
|
||||
* return only necessary fields
|
||||
* do not expose internal metadata
|
||||
* do not expose password hashes, verification token hashes, session token hashes, or internal metadata
|
||||
* expose editor attribution with only `id` and `displayName`
|
||||
* keep API response shapes consistent with `frontend/src/services/api.ts`
|
||||
|
||||
* i18n:
|
||||
|
||||
* use `languages` and `entity_translations` for entity translations
|
||||
* use `X-Locale` for localized API reads
|
||||
* keep base `name` / `title` fields as the default-language source
|
||||
* do not let localized editing overwrite the base field unintentionally
|
||||
* include translations only where the current API shape already supports them
|
||||
|
||||
* Editing and audit:
|
||||
|
||||
* create/update/delete operations on Wiki content should record editor information
|
||||
* detail pages should continue to support edit metadata and edit history
|
||||
* delete or update behavior must not leak internal audit payloads to normal UI
|
||||
|
||||
---
|
||||
|
||||
@@ -96,11 +196,15 @@ Violations are considered critical errors.
|
||||
|
||||
* Components: `PascalCase`
|
||||
* Composables: `useXxx`
|
||||
|
||||
* General:
|
||||
|
||||
* variables/functions: `camelCase`
|
||||
* Keep files focused and under reasonable length
|
||||
* Avoid duplication
|
||||
* TypeScript types/interfaces: match existing local style
|
||||
|
||||
* Keep files focused and under reasonable length.
|
||||
* Avoid duplication.
|
||||
* Prefer existing helper APIs and local patterns over introducing new abstractions.
|
||||
|
||||
---
|
||||
|
||||
@@ -110,10 +214,10 @@ This project is developed from WSL, but runtime validation is done through Docke
|
||||
|
||||
Agent workflow:
|
||||
|
||||
* Run:
|
||||
* Run when practical:
|
||||
|
||||
* lint
|
||||
* typecheck
|
||||
* `pnpm lint`
|
||||
* `pnpm typecheck`
|
||||
|
||||
* Do NOT run tests in WSL.
|
||||
* Do NOT require local test execution before finishing a task.
|
||||
@@ -128,12 +232,13 @@ When adding tests is clearly useful, keep them focused and minimal, but do not e
|
||||
|
||||
A task is complete ONLY IF:
|
||||
|
||||
* Matches `DESIGN.md`
|
||||
* Minimal diff (no unrelated changes)
|
||||
* No UI leaks of internal info
|
||||
* Code is readable and concise
|
||||
* Passes lint/typecheck when practical
|
||||
* Docker runtime issues are handled from user-provided `docker compose up --build` output
|
||||
* Matches `DESIGN.md`.
|
||||
* Updates `DESIGN.md` when the implemented behavior changes product, API, schema, permission, route, or i18n expectations.
|
||||
* Minimal diff, with no unrelated changes.
|
||||
* No UI leaks of internal info.
|
||||
* Code is readable and concise.
|
||||
* Passes lint/typecheck when practical.
|
||||
* Docker runtime issues are handled from user-provided `docker compose up --build` output.
|
||||
|
||||
---
|
||||
|
||||
@@ -143,6 +248,7 @@ A task is complete ONLY IF:
|
||||
* Over-engineering simple features
|
||||
* Creating unused files or abstractions
|
||||
* Mixing internal/debug data into UI
|
||||
* Exposing token/hash/internal audit data through public API responses
|
||||
* Large, unfocused commits
|
||||
* Silent behavior changes outside scope
|
||||
|
||||
@@ -150,17 +256,7 @@ A task is complete ONLY IF:
|
||||
|
||||
## When Unsure
|
||||
|
||||
* Ask for clarification
|
||||
* Do not guess requirements
|
||||
* Do not invent features not in `DESIGN.md`
|
||||
|
||||
---
|
||||
|
||||
## Project Context
|
||||
|
||||
* Goal: Pokopia Wiki
|
||||
* Stack:
|
||||
|
||||
* Frontend: Vue
|
||||
* Backend: Node + PostgreSQL
|
||||
* Infra: Docker
|
||||
* Ask for clarification.
|
||||
* Do not guess requirements.
|
||||
* Do not invent features not in `DESIGN.md`.
|
||||
* If current code and `DESIGN.md` disagree, call out the mismatch before changing behavior.
|
||||
|
||||
Reference in New Issue
Block a user