initial commit

AGENTS.md

@@ -0,0 +1,155 @@
+# AGENTS.md
+
+## Core Principles
+
+* Always read `DESIGN.md` before making any change.
+* Follow the existing structure and conventions strictly.
+* Make **minimal, targeted changes only**. Do not refactor unrelated code.
+* Prefer clarity over cleverness. Avoid unnecessary abstraction.
+
+---
+
+## Mandatory Workflow (MUST FOLLOW)
+
+For any non-trivial task:
+
+1. **Read `DESIGN.md`**
+2. **Produce a short plan (no code)**
+3. Wait for approval
+4. Implement in small steps
+5. Run lightweight validation when practical (lint/typecheck). Do not run tests in WSL.
+
+Do NOT skip planning.
+
+---
+
+## Scope Control (Prevent Code Bloat)
+
+* Only modify files directly related to the task.
+* Do NOT:
+
+  * Introduce new layers (services, utils, hooks, etc.) unless clearly required
+  * Split files unnecessarily
+  * Rewrite existing modules without explicit instruction
+* Prefer editing existing files over creating new ones.
+* Keep functions and components small and readable.
+
+If a task grows beyond scope, STOP and ask.
+
+---
+
+## UI Safety Rules (CRITICAL)
+
+User-facing UI must NEVER contain:
+
+* prompts
+* remarks
+* planning notes
+* debug messages
+* explanations of what was changed
+* internal field names like `debug`, `meta`, `internal`
+
+### Strict Rules
+
+* 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
+
+Violations are considered critical errors.
+
+---
+
+## Data & API Design Rules
+
+* Follow `DESIGN.md` as the **single source of truth**
+* PostgreSQL:
+
+  * use `snake_case`
+  * define proper primary/foreign keys
+  * avoid premature optimization
+* APIs:
+
+  * return only necessary fields
+  * do not expose internal metadata
+
+---
+
+## Code Style & Structure
+
+* Vue:
+
+  * Components: `PascalCase`
+  * Composables: `useXxx`
+* General:
+
+  * variables/functions: `camelCase`
+* Keep files focused and under reasonable length
+* Avoid duplication
+
+---
+
+## Testing & Validation
+
+This project is developed from WSL, but runtime validation is done through Docker.
+
+Agent workflow:
+
+* Run:
+
+  * lint
+  * typecheck
+
+* Do NOT run tests in WSL.
+* Do NOT require local test execution before finishing a task.
+* The user will run `docker compose up --build`.
+* If Docker reports errors, the user will paste the error output and the agent will fix those errors in a follow-up pass.
+
+When adding tests is clearly useful, keep them focused and minimal, but do not execute them locally unless explicitly requested.
+
+---
+
+## Definition of Done
+
+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
+
+---
+
+## Anti-Patterns (STRICTLY FORBIDDEN)
+
+* Adding UI remarks like "I updated this"
+* Over-engineering simple features
+* Creating unused files or abstractions
+* Mixing internal/debug data into UI
+* Large, unfocused commits
+* Silent behavior changes outside scope
+
+---
+
+## 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