Skip to content

INSTRUCTIONS.md

Latest commit

 

History

History
125 lines (91 loc) · 3.98 KB

INSTRUCTIONS.md

File metadata and controls

125 lines (91 loc) · 3.98 KB
Raw

AI Development Guidelines

Agent-specific instructions are in .agents/ subfolders and override these guidelines.

Core Principles

Minimalism

  • Only write what's necessary, avoid over-engineering
  • Less code = less maintenance

Code Quality

  • Prioritize clarity over cleverness
  • Use meaningful names and simple logic

No Duplicate Code

  • Extract shared logic into reusable modules
  • If you write the same code twice, refactor it

Small Functions

  • Under ~100 lines
  • Single purpose

Testing

  • Focus on critical paths and edge cases, not the obvious
  • Keep tests short and simple

Documentation

  • Document "why", not "what" (code shows what)
  • Keep docs near the code
  • Update docs when code changes

DX First

When modifying interfaces or their usage:

  1. Update documentation first
  2. Ensure the design is clear and simple to use
  3. Then implement the changes

Why: Writing docs first forces you to think through the API from the user's perspective before coding.

Changesets

When modifying packages that are published (check for "private": true in package.json):

  • Create a changeset file in .changeset/ with a random filename (e.g., happy-tiger-123.md): 
    ---
"package-name": patch
---

Short summary of the change from user's perspective
  • Bump types: patch (bug fixes), minor (new features), major (breaking changes)
  • Skip changesets for: docs-only changes, test-only changes, internal tooling

Why: Changesets automate versioning and changelog generation, ensuring users know what changed between releases.

Plans

Store in /.plans/ with date prefix (e.g., 2026-01-27-feature-name.md).

  • Keep plans focused on one feature/system
  • Include a Progress section with task status table
  • Plans are temporary: delete when complete, preserve knowledge in code and docs

When starting a task, review existing plans in /.plans/ to find relevant context.

Task Management

Plans are living documents that evolve as understanding grows:

  • Break work into concrete, actionable tasks
  • Update task definitions as you learn more
  • Add new tasks as complexity is discovered
  • Remove or merge tasks that become unnecessary

If a task proves too complex:

  • Pause to research and understand the problem deeper
  • Break it into smaller tasks and update the plan
  • This is valid progress - don't force completion of oversized tasks

Risk-First Prioritization

Always pick the highest-risk task first - the one with most uncertainty:

  • Unknown technical feasibility → tackle first
  • Unclear requirements → clarify and implement early
  • Complex integrations → prove them before building around them

Why: Early failures are cheap. Discovering a blocker after building dependent features is expensive.

Keeping Plans Current

After completing any task:

  • Mark it done in the Progress table
  • Update remaining task definitions if understanding changed
  • Add new tasks discovered during implementation
  • Revise estimates/scope based on what you learned

Completing Plans

When all tasks in a plan are done:

  1. Preserve knowledge before deleting:

    • Add TODO: comments in code for future enhancements mentioned in the plan
    • Document architectural decisions with "why" comments where non-obvious
    • Update README or other docs if the plan contained user-facing information
    • Ensure any competitor analysis or research insights are captured where relevant

  2. Delete the plan file - Plans are temporary; don't let them accumulate

Why: Plans contain valuable context (future ideas, design rationale, research). Embedding this in code/docs keeps it discoverable and maintained, while removing the stale plan file.

Pre-PR Validation

All steps must pass before submitting:

pnpm install --frozen-lockfile
pnpm lint    # Run 'pnpm fix' to auto-fix
pnpm build
pnpm test

Checklist

  • Lint passes
  • Build succeeds
  • Tests pass
  • README updated (if user-facing changes)
  • Changeset added (if modifying published packages)