pokopiawiki.tootaio.com/AGENTS.md

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. For UI, component, layout, or styling tasks, also read DesignGuidelines.html
3. Produce a short plan (no code)
4. Wait for approval
5. Implement in small steps
6. Run lightweight validation when practical (lint/typecheck). Do not run tests in WSL.

Do NOT skip planning.

---

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.
• 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.

---

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