Skip to content

AGENTS.md

Latest commit

 

History

History
222 lines (159 loc) · 10 KB

AGENTS.md

File metadata and controls

222 lines (159 loc) · 10 KB
Raw

DataDoe Starter Agent Rules

1) Purpose of this repository

This repository is a starter template for building apps that use the DataDoe API with Amazon seller/vendor account data.

Your goal in this repo is to:

  • help build simple, stable business apps on top of DataDoe data,
  • keep implementation understandable for non-technical users,
  • avoid unnecessary complexity.

2) Repository context

Before any planning or implementation, you must read README.md in the project root to understand what this starter repository is, what it includes, its tech stack, and how it works.

  • README.md is the source of truth for the repository purpose, included features, tech stack, usage instructions, and DataDoe API references.
  • If README.md content conflicts with your assumptions, README.md wins.
  • Do not skip this step — context from README.md informs all subsequent decisions.

3) Work style for non-technical users

  • Use simple language.
  • If user request is vague (for example: "I want to see XYZ"), ask follow-up questions first.
  • Confirm understanding before implementation when requirements are unclear.
  • Prefer safe, predictable implementations over clever ones.
  • After creating an implementation plan, explain it to the user at a high level (what will be built), without deep file/code details unless user asks.

4) Mandatory DataDoe API readiness flow (before implementation)

Before implementing any feature, perform this exact flow:

  1. Check if .env.local exists.
  2. If missing, create .env.local based on .env.example.
  3. Verify DATADOE_API_KEY is present and non-empty.
  4. Run a health check request with curl against:
    • https://api.datadoe.com/api/v1/util/sellers-and-vendors
    • header: datadoe-api-key: <DATADOE_API_KEY>
  5. If key is missing/invalid:
    • ask user in chat to provide the DataDoe API key,
    • write the key into .env.local on behalf of the user.
  6. Repeat key check + health check until connection succeeds.
  7. Do not continue to implementation planning or coding until the health check succeeds.

Note

  • You should do key pasting for non-technical users (do not force manual IDE editing).
  • Never print full secrets back to user.

5) Starter flush procedure (before building custom features)

This repository is a ready-to-use proof of concept. Out of the box, with only a DataDoe API key configured, the included dashboard app is fully operational. However, when you begin building a custom app for the user, you must flush the starter feature code first before writing any new feature code.

Flush trigger

The flush is required when the user asks you to build something new (a custom app, new features, a different dashboard, etc.). Do not flush if the user only wants to run, inspect, or make minor tweaks to the existing starter dashboard.

What to flush (remove)

  • src/features/dashboard/ — entire directory (components, hooks, lib, types, barrel export)
  • src/app/api/dashboard/route.ts — dashboard-specific API route
  • Dashboard import and rendering from src/app/page.tsx — replace with an empty/placeholder page

What to keep (do not touch)

  • src/components/ui/* — all generic shadcn components (badge, button, card, select, table, data-table)
  • src/app/globals.css — global styles and design tokens
  • src/app/layout.tsx — root layout
  • src/app/page.tsx — keep the file itself, only clear dashboard content
  • src/app/providers.tsx — React Query provider setup
  • src/lib/datadoe-client.ts — DataDoe Axios client with auth and error handling
  • src/lib/utils.ts — Tailwind class merge utility
  • src/app/api/sellers/route.ts — generic seller/vendor account fetching (entry point for most DataDoe apps)
  • src/app/api/datadoe/[...path]/route.ts — generic DataDoe API proxy
  • src/types/api/* — shared API types (exports, sellers)

Implementation prerequisites (all three required before coding)

Do not start writing new feature code until all three conditions are met:

  1. You have explicit requirements from the user (what to build).
  2. You have prepared an implementation plan accepted by the user.
  3. The starter feature code has been flushed per the rules above.

6) Implementation discipline

  • Follow user requirements and approved implementation plan strictly.
  • Do not add extra features not requested by the user.
  • Keep scope tight and explicit.
  • If new ambiguity appears during implementation, pause and ask follow-up questions.

7) Folder structure guidelines

This repository follows a feature-based folder structure. All code related to a specific product feature lives inside its own module under src/features/. Generic, reusable code lives in shared directories.

Reference structure

src/
├── app/                        # Next.js App Router: pages, layouts, API routes
│   ├── api/                    # Server-side API route handlers
│   │   └── <feature>/          # Feature-specific API routes
│   ├── <route>/                # Route segments (pages + layouts)
│   ├── globals.css             # Global styles
│   ├── layout.tsx              # Root layout
│   ├── page.tsx                # Home page
│   └── providers.tsx           # App-wide providers
├── components/                 # Generic, reusable UI components
│   └── ui/                     # shadcn/design-system primitives
├── features/                   # Feature modules (one folder per product feature)
│   └── <feature-name>/
│       ├── components/         # UI components specific to this feature
│       ├── hooks/              # React hooks specific to this feature
│       ├── lib/                # Helpers, mappers, utilities for this feature
│       ├── types/              # TypeScript types for this feature
│       └── index.ts            # Public barrel export
├── lib/                        # Shared utilities (API client, helpers)
└── types/                      # Shared TypeScript types
    └── api/                    # API request/response types

Placement rules

  • Feature-specific code (components, hooks, helpers, types used only by one feature) goes into src/features/<feature-name>/.
  • Reusable UI components (no business logic, usable across features) go into src/components/ui/.
  • Shared utilities (API client, generic helpers) go into src/lib/.
  • Shared types (API DTOs, cross-feature types) go into src/types/.
  • API route handlers go into src/app/api/<feature>/ for feature-specific routes, or src/app/api/ root level for generic routes.
  • Each feature module must have a barrel index.ts that exports its public API.
  • Never import internal feature files from outside the feature — always import through the barrel index.ts.

8) Quality gates (required after each finished feature)

After finishing a feature:

  • run lint checks,
  • run build/type checks,
  • fix detected issues before finishing.

9) Optional localhost sharing via ngrok (after implementation)

When implementation is complete and the app is working, ask the user if they want to share temporary public access to their local app through ngrok.

If user confirms, provide this manual:

  1. Install ngrok on macOS (Terminal):

    brew install ngrok

  2. For other operating systems, use the official guide:

  3. Configure ngrok auth token:

    ngrok config add-authtoken "<YOUR_AUTHTOKEN>"

  4. Start a public endpoint:

    ngrok http 3000

Never expose user secrets in chat (API keys, ngrok auth token values, etc.).

10) UI and styling rules

  • Always follow style/design constraints from DESIGN.md.
  • Do not introduce styles outside those design rules unless user explicitly requests it.

11) Error handling expectations

  • Implement user-friendly errors for non-technical users.
  • Surface clear next steps (what to do next) when possible.
  • If bug is reported, reproduce, isolate cause, fix, and verify.

12) DataDoe API reference requirement

For every API-related implementation, debugging task, or schema/data mapping change:

  • always reference DataDoe API documentation first: https://api.datadoe.com/api/v1/docs
  • always reference DataDoe data scheme JSON: https://api.datadoe.com/api/v1/spec/data-scheme
  • validate endpoint requirements, field names, and payload shape against these sources before coding
  • if code and docs conflict, treat the DataDoe docs/scheme as source of truth and adjust implementation

13) Engineering best practices (mandatory)

Always apply strong software engineering practices, especially for API-driven features.

API integration

  • Use typed request/response models.
  • Validate payloads and response assumptions.
  • Keep API calls centralized (shared client/helpers), avoid duplicated request logic.
  • Keep secrets server-side only.
  • Respect API limits and constraints (rate limits, retries, backoff, timeouts).

Async and polling / near real-time flows

  • Design async operations to be safe and predictable.
  • Avoid uncontrolled parallelism that can break rate limits.
  • Use explicit polling intervals, stop conditions, and timeout guards.
  • Handle partial/in-progress states clearly.
  • Ensure polling loops can terminate and report useful errors.

Response processing and error handling

  • Parse and map API responses defensively.
  • Handle missing/nullable fields safely.
  • Provide actionable, user-friendly messages for non-technical users.
  • Preserve technical trace context when available (for example request IDs).
  • Differentiate validation, auth, rate-limit, not-found, and server errors.

Frontend patterns

  • Use best-practice frontend architecture and state patterns.
  • Prefer predictable data-fetching patterns (query keys, caching strategy, enabled conditions).
  • Keep UI components focused and reusable.
  • Prevent duplicate requests and invalid user actions with clear disabled/loading states.
  • Keep UX clear during loading, empty, error, and success states.