Vibecode like an engineer

65 templates, ready to copy or download into your project. Agents build what you describe; these files are how you describe it once instead of in every prompt.

No agent reads every Markdown file automatically. Each loads its own instruction files; everything else, you reference.

# One source of truth for every agent

AGENTS.md                         # the shared instructions (Codex, Cursor, Copilot, Claude Code)
CLAUDE.md                         # only if you need Claude-specific notes; first line: @AGENTS.md
GEMINI.md                         # only if you use Gemini CLI; first line: @AGENTS.md
.github/copilot-instructions.md   # only for Copilot chat surfaces; points to AGENTS.md

# Or let Gemini CLI read AGENTS.md directly, in .gemini/settings.json:
{ "context": { "fileName": ["AGENTS.md", "GEMINI.md"] } }

Tools change quickly. If something here doesn't match your version, the linked docs are the source of truth.

Works with any coding agent. Each step has a prompt, what you should get back, and when you're done.

1. 1

   Repository reconnaissance

   Learn the stack, structure and conventions before changing anything.

   You get

   A report of stack, modules, commands, conventions and unknowns.

   Done when

   You agree with the report, and the commands it ran worked.

   Prompt: Repository reconnaissance

   Explore this repository without modifying any files.
   
   Report:
   1. Stack: languages, frameworks, package manager, runtime versions (cite the files you read).
   2. Structure: the main modules and what each owns.
   3. Commands: how to install, run, build, lint, type check and test. Run the safe read-only ones and show their output.
   4. Conventions: naming, formatting, error handling, state management, testing style. Give one example file for each.
   5. Existing context docs: list any README, AGENTS.md, CLAUDE.md, docs/ files and what they cover.
   6. Unknowns: anything you couldn't determine. Do not guess.
   
   Output a concise report. Do not write code.

   Copy
2. 2

   Requirements discovery

   Turn the idea into decisions you've confirmed.

   You get

   PROJECT_BRIEF.md with facts, assumptions and open questions separated.

   Done when

   No open question blocks the MVP.

   Prompt: Requirements discovery

   I want to build [ONE-LINE IDEA]. Interview me to turn this into a project brief.
   
   Rules:
   - Ask one question at a time, most important first.
   - Cover: the problem, target users, main user journeys, must-have features, non-goals, constraints (budget, stack, deadline, hosting, regions), success metrics, and risks.
   - After each answer, note whether it's a confirmed fact, an assumption or still open.
   
   When I say "done", write PROJECT_BRIEF.md with sections: Problem, Users, Journeys, Requirements (FR-1...), Non-functional requirements, Non-goals, Constraints, Assumptions, Open questions, Success metrics.

   Copy
3. 3

   Research

   Verify technical choices against official docs.

   You get

   Options with trade-offs and links, and one recommendation.

   Done when

   Every key dependency is chosen, with a link to its docs.

   Prompt: Technical research

   Research options for [DECISION, e.g. "authentication for a Next.js app"] given these constraints: [CONSTRAINTS].
   
   For each of 2 to 4 options:
   - What it is, current version, license and pricing (link the official page you used).
   - Fit with our stack in [FILES OR docs/TECH_STACK.md].
   - Trade-offs, risks and lock-in.
   
   Use official documentation only. If you can't verify something, say "unverified". Recommend one option and explain why, but don't implement anything.

   Copy
4. 4

   Context generation

   Write only the context documents this project needs, in dependency order.

   You get

   AGENTS.md plus the selected docs: architecture, data, API, design, security, testing.

   Done when

   Each document is reviewed; unknowns are listed, not guessed.

   Prompt: Context-file planning

   Read PROJECT_BRIEF.md and the repository.
   
   Propose the minimum set of context documents this project needs, using this list as a menu, not a checklist: AGENTS.md, README.md, REQUIREMENTS.md, docs/ARCHITECTURE.md, docs/TECH_STACK.md, docs/DESIGN_SYSTEM.md, docs/DATABASE_SCHEMA.md, docs/API_SPEC.md, docs/INTEGRATIONS.md, docs/SECURITY.md, docs/TESTING_STRATEGY.md, docs/DEPLOYMENT.md, IMPLEMENTATION_PLAN.md, TASKS.md, DECISIONS.md.
   
   For each proposed file: why it's needed, what it will contain, what it depends on. List files you deliberately left out and why.
   Then generate them in dependency order, one at a time, marking anything uncertain as an open question. Stop after each file for my review.

   Copy
5. 5

   Human review

   You check requirements, architecture, data model, integrations, security and costs.

   You get

   Approved documents, and ADRs for significant decisions.

   Done when

   You'd be comfortable if another developer built from these docs.

   No prompt: this step is yours. Read the docs the agent wrote and decide.

6. 6

   Implementation planning

   Break the work into small, testable tasks.

   You get

   IMPLEMENTATION_PLAN.md and TASKS.md with dependencies and acceptance criteria.

   Done when

   Every task fits in one reviewable diff and maps to requirements.

   Prompt: Break down into tasks

   Read PROJECT_BRIEF.md, REQUIREMENTS.md and docs/ARCHITECTURE.md. Create IMPLEMENTATION_PLAN.md and TASKS.md.
   
   Each task must:
   - Be small enough for one reviewable diff (roughly under 300 changed lines).
   - Have an ID, a clear outcome, the files likely touched, dependencies on other tasks, the requirement IDs it covers, and acceptance criteria.
   - Include how to verify it (tests or commands).
   
   Order tasks so the app runs end to end as early as possible. Mark risky tasks. Don't implement anything yet.

   Copy
7. 7

   Implementation

   One coherent task at a time, following the agreed docs.

   You get

   A focused diff, with checks run and a summary of changed files.

   Done when

   Acceptance criteria met, and you've read the diff.

   Prompt: Implement one task

   Implement task [TASK ID] from TASKS.md: [TASK TITLE].
   
   Context: follow AGENTS.md, docs/CODING_STANDARDS.md and [RELEVANT DOCS].
   Constraints: only touch files needed for this task. No new dependencies without asking. No unrelated refactors. Match the surrounding code style.
   Acceptance criteria: [CRITERIA].
   
   Steps:
   1. Restate the task and list assumptions. Ask if anything is unclear.
   2. Show a short plan, then implement.
   3. Run [FORMAT, LINT, TYPECHECK, TEST COMMANDS] and show the output.
   4. Summarize every changed file and why, update affected docs, and mark the task in TASKS.md.
   Report anything skipped or failing honestly.

   Copy
8. 8

   Verification and doc updates

   Prove it works with real commands, and keep docs in sync.

   You get

   Check results table, updated docs and remaining risks.

   Done when

   Every check ran and passed, or failures are recorded honestly.

   Prompt: Run and verify tests

   Verify the current changes.
   
   Run, in order: [INSTALL], [FORMAT CHECK], [LINT], [TYPECHECK], [UNIT TESTS], [INTEGRATION OR E2E TESTS], [BUILD].
   For each command report: the exact command, exit code, and the relevant output.
   
   Then give a table: check | passed / failed / skipped / not run | notes.
   Do not change tests to make them pass. Do not say "all tests pass" unless every command above ran and passed.

   Copy
9. 9

   Handoff and maintenance

   Leave the project so the next session, or person, can continue.

   You get

   AGENT_HANDOFF.md, TASKS.md, DECISIONS.md and KNOWN_ISSUES.md updated.

   Done when

   A fresh session can continue from the handoff alone.

   Prompt: Session handoff

   We're ending this session. Update AGENT_HANDOFF.md with:
   
   - Goal of the session and what was completed (task IDs).
   - Current state: what works, what's in progress, what's broken.
   - Decisions made and why (also add significant ones to DECISIONS.md).
   - Commands run and their results (tests, builds).
   - Known issues and risks (also update KNOWN_ISSUES.md).
   - Exact next steps, in order, for the next session.
   
   Keep it under 60 lines. Be factual; don't mark anything done that wasn't verified.

   Copy

Replace the [PLACEHOLDERS]. Every template asks the agent to show what it ran and what it found, not just its conclusion.

Explore this repository without modifying any files.

Report:
1. Stack: languages, frameworks, package manager, runtime versions (cite the files you read).
2. Structure: the main modules and what each owns.
3. Commands: how to install, run, build, lint, type check and test. Run the safe read-only ones and show their output.
4. Conventions: naming, formatting, error handling, state management, testing style. Give one example file for each.
5. Existing context docs: list any README, AGENTS.md, CLAUDE.md, docs/ files and what they cover.
6. Unknowns: anything you couldn't determine. Do not guess.

Output a concise report. Do not write code.

I want to build [ONE-LINE IDEA]. Interview me to turn this into a project brief.

Rules:
- Ask one question at a time, most important first.
- Cover: the problem, target users, main user journeys, must-have features, non-goals, constraints (budget, stack, deadline, hosting, regions), success metrics, and risks.
- After each answer, note whether it's a confirmed fact, an assumption or still open.

When I say "done", write PROJECT_BRIEF.md with sections: Problem, Users, Journeys, Requirements (FR-1...), Non-functional requirements, Non-goals, Constraints, Assumptions, Open questions, Success metrics.

Research options for [DECISION, e.g. "authentication for a Next.js app"] given these constraints: [CONSTRAINTS].

For each of 2 to 4 options:
- What it is, current version, license and pricing (link the official page you used).
- Fit with our stack in [FILES OR docs/TECH_STACK.md].
- Trade-offs, risks and lock-in.

Use official documentation only. If you can't verify something, say "unverified". Recommend one option and explain why, but don't implement anything.

Read PROJECT_BRIEF.md and the repository.

Propose the minimum set of context documents this project needs, using this list as a menu, not a checklist: AGENTS.md, README.md, REQUIREMENTS.md, docs/ARCHITECTURE.md, docs/TECH_STACK.md, docs/DESIGN_SYSTEM.md, docs/DATABASE_SCHEMA.md, docs/API_SPEC.md, docs/INTEGRATIONS.md, docs/SECURITY.md, docs/TESTING_STRATEGY.md, docs/DEPLOYMENT.md, IMPLEMENTATION_PLAN.md, TASKS.md, DECISIONS.md.

For each proposed file: why it's needed, what it will contain, what it depends on. List files you deliberately left out and why.
Then generate them in dependency order, one at a time, marking anything uncertain as an open question. Stop after each file for my review.

Using PROJECT_BRIEF.md and REQUIREMENTS.md, draft docs/ARCHITECTURE.md.

Include:
- Context: users and external systems (Mermaid diagram).
- Containers and modules with responsibilities and boundaries.
- Data flow for the two most important user journeys.
- Auth model, error handling, caching and background work.
- Technology choices with one-line reasons, and rejected alternatives.
- Risks, trade-offs and open questions.

Prefer the simplest design that meets the requirements. For each significant decision, also draft an ADR in docs/adr/. Don't write application code.

Create docs/DESIGN_SYSTEM.md and docs/UI_UX_SPEC.md for [PRODUCT].

Brand and tone: [ADJECTIVES, REFERENCES OR SCREENSHOTS]. Existing tokens or components: [PATHS, if any].

DESIGN_SYSTEM.md: tokens (color with light and dark values, type scale, spacing, radius, shadow, motion), components with usage rules, accessibility rules (WCAG 2.2 AA).
UI_UX_SPEC.md: every screen with purpose, layout, components used, and its loading, empty, error and success states, plus responsive behavior at [BREAKPOINTS].

Reuse existing tokens and components where they exist. Flag any screen where requirements are unclear.

Design the data model for [FEATURES] using [DATABASE].

Deliver:
1. docs/DATABASE_SCHEMA.md: entities, relationships (Mermaid ER diagram), constraints, indexes with the query each one serves, and tenant or user isolation rules.
2. The first migration in [MIGRATION TOOL AND PATH], with a down migration.
3. Seed data for local development.

Explain any denormalization. List access patterns you assumed. Don't run migrations; I'll review and run them.

We're integrating [PROVIDER] for [PURPOSE]. Official docs: [LINKS].

Write docs/INTEGRATIONS.md section for it:
- Exact SDK or API version, endpoints and methods we'll use (link each to its doc page).
- Auth and required environment variables (add them to .env.example without values).
- Webhooks: events, signature verification, retries, idempotency.
- Errors, rate limits, timeouts and how we'll map them.
- Sandbox setup and how we'll test it.

Only use methods you found in the linked docs. If something isn't documented, list it as an open question instead of guessing.

Create docs/THREAT_MODEL.md for [SYSTEM OR FEATURE] based on docs/ARCHITECTURE.md.

1. Assets worth protecting and who might attack them.
2. Trust boundaries and data flows (Mermaid diagram).
3. Threats per boundary using STRIDE, including prompt injection if the app or its agents read untrusted content.
4. For each threat: likelihood, impact, existing control, missing control.
5. A prioritized list of fixes, each mapped to a test that would prove it works.

Reference OWASP Top 10:2025 and ASVS where relevant. Don't change code.

Read PROJECT_BRIEF.md, REQUIREMENTS.md and docs/ARCHITECTURE.md. Create IMPLEMENTATION_PLAN.md and TASKS.md.

Each task must:
- Be small enough for one reviewable diff (roughly under 300 changed lines).
- Have an ID, a clear outcome, the files likely touched, dependencies on other tasks, the requirement IDs it covers, and acceptance criteria.
- Include how to verify it (tests or commands).

Order tasks so the app runs end to end as early as possible. Mark risky tasks. Don't implement anything yet.

Implement task [TASK ID] from TASKS.md: [TASK TITLE].

Context: follow AGENTS.md, docs/CODING_STANDARDS.md and [RELEVANT DOCS].
Constraints: only touch files needed for this task. No new dependencies without asking. No unrelated refactors. Match the surrounding code style.
Acceptance criteria: [CRITERIA].

Steps:
1. Restate the task and list assumptions. Ask if anything is unclear.
2. Show a short plan, then implement.
3. Run [FORMAT, LINT, TYPECHECK, TEST COMMANDS] and show the output.
4. Summarize every changed file and why, update affected docs, and mark the task in TASKS.md.
Report anything skipped or failing honestly.

Bug: [WHAT HAPPENS]. Expected: [WHAT SHOULD HAPPEN].
Reproduce: [STEPS OR COMMAND]. Error output:
[PASTE EXACT ERROR AND STACK TRACE]
Environment: [OS, RUNTIME, BROWSER, VERSION]. Already tried: [ATTEMPTS].

1. Reproduce it and show the output.
2. Find the root cause and explain it with file and line references. Don't fix yet.
3. Write a failing test that captures the bug.
4. Propose the smallest fix, implement it, and show the test now passes along with the full suite.

Verify the current changes.

Run, in order: [INSTALL], [FORMAT CHECK], [LINT], [TYPECHECK], [UNIT TESTS], [INTEGRATION OR E2E TESTS], [BUILD].
For each command report: the exact command, exit code, and the relevant output.

Then give a table: check | passed / failed / skipped / not run | notes.
Do not change tests to make them pass. Do not say "all tests pass" unless every command above ran and passed.

Review the diff of [BRANCH OR COMMIT RANGE] against main. You didn't write this code; be skeptical.

Check: correctness against [TASK OR ACCEPTANCE CRITERIA], edge cases, error handling, security (auth, validation, injection, secrets), performance, test coverage, consistency with docs/CODING_STANDARDS.md, and unnecessary changes or dependencies.

For each finding: file and line, severity (blocker, major, minor), why it matters, and a suggested fix. Separate confirmed problems from suspicions. Don't edit files.

[PAGE, ENDPOINT OR JOB] is slow: [MEASUREMENT, e.g. "p95 1.8 s, target 300 ms"].

1. Measure a baseline with [TOOL OR COMMAND] and show the numbers.
2. Profile and identify the top three costs, with evidence.
3. For each, propose one change and its expected gain.
4. Implement the most valuable change only, re-measure, and show before and after.
Don't optimize anything you haven't measured.

Audit this project for production readiness. Read docs/DEPLOYMENT.md, docs/SECURITY.md and docs/TESTING_STRATEGY.md first.

Check and report pass, fail or unknown, with evidence, for: environment config and secrets, auth and authorization, input validation, error tracking and logging, health checks, backups and a tested restore, database migrations, rate limiting, security headers, dependency audit, accessibility basics, performance budgets, rollback plan, and runbooks.

List blockers first. For each gap, the smallest fix. Don't deploy anything.

We're ending this session. Update AGENT_HANDOFF.md with:

- Goal of the session and what was completed (task IDs).
- Current state: what works, what's in progress, what's broken.
- Decisions made and why (also add significant ones to DECISIONS.md).
- Commands run and their results (tests, builds).
- Known issues and risks (also update KNOWN_ISSUES.md).
- Exact next steps, in order, for the next session.

Keep it under 60 lines. Be factual; don't mark anything done that wasn't verified.

Tasklight: a small team task app with a paid plan. Small enough to follow, real enough to show the practice.

1. 1. The vague idea

   "I want a simple app where small teams can track tasks, with a paid plan."
   
   Too vague for an agent: who are the users, what is "simple", what does paying unlock, what stack, where is it hosted?

2. 2. The improved brief (PROJECT_BRIEF.md)

   Name: Tasklight
   Problem: Teams of 2 to 10 people lose track of small tasks in chat.
   Users: Team owner (creates workspace, pays), members (create and complete tasks).
   Journeys: sign up, create workspace, invite member, add task, assign, complete.
   MVP: workspaces, invites by email, tasks with title, assignee, due date and status.
   Paid plan: Free up to 3 members; Pro ($6 per workspace per month) for unlimited members.
   Non-goals: comments, file attachments, mobile apps, integrations.
   Constraints: Next.js, Postgres, hosted on Vercel and Neon, payments through a merchant of record.
   Success: a team of 3 can go from sign-up to first completed task in under 5 minutes.

3. 3. Requirements and acceptance criteria

   FR-3 Create task: a member can create a task with a title (1 to 120 chars), optional assignee and due date.
     Given I'm a member of workspace W
     When I submit a task titled "Ship v1"
     Then it appears at the top of W's task list with status "open"
     And members of other workspaces can't see it
   
   FR-7 Member limit: a Free workspace can't have more than 3 members.
     Given W is on Free with 3 members
     When the owner invites a 4th
     Then the invite is blocked with an upgrade prompt

4. 4. Architecture and design decisions

   Architecture: one Next.js app (UI plus route handlers), Postgres via an ORM, background email through a queue-less provider call. No microservices.
   ADR-0001: Use a merchant of record for billing so we don't handle global sales tax ourselves.
   ADR-0002: Row-level workspace isolation: every query filters by workspace_id from the session, never from the request body.
   Design: tokens and components in docs/DESIGN_SYSTEM.md; every list has empty, loading and error states.

5. 5. Database and API considerations

   Tables: users, workspaces, memberships (user_id, workspace_id, role), tasks (workspace_id, title, assignee_id, due_on, status), subscriptions.
   Constraints: unique (user_id, workspace_id) on memberships; tasks.title length check; foreign keys with on delete cascade for tasks.
   Index: tasks (workspace_id, status, created_at desc) for the main list.
   API: POST /api/tasks, PATCH /api/tasks/:id, documented in docs/API_SPEC.md. Billing webhooks documented in docs/WEBHOOKS.md.

6. 6. Security requirements

   - Every API route checks the session and membership of the workspace.
   - workspace_id always comes from the server-side membership lookup.
   - Invite tokens are random, single-use and expire in 7 days.
   - Billing webhook verifies the provider signature and is idempotent by event ID.
   - Rate limit sign-in and invites. Secrets only in environment variables.

7. 7. Testing strategy

   Unit: validation and plan-limit rules.
   Integration: task API with a test database; a member of workspace A can't read B's tasks.
   End-to-end (Playwright): sign up, create workspace, add task, complete it.
   Webhook: replay a recorded test event twice and assert one subscription change.
   CI runs lint, typecheck, tests and build on every pull request.

8. 8. Initial implementation plan (TASKS.md)

   T-01 Project setup, lint, typecheck, CI (no features)
   T-02 Database schema and first migration (FR-1 to FR-4)
   T-03 Auth and workspace creation (FR-1, FR-2)
   T-04 Create and list tasks (FR-3)  depends on T-02, T-03
   T-05 Complete and assign tasks (FR-4, FR-5)
   T-06 Invites and member limit (FR-6, FR-7)
   T-07 Billing with webhooks (FR-8)
   T-08 Empty, loading and error states; accessibility pass

9. 9. A precise implementation prompt

   Implement T-04 from TASKS.md: create and list tasks (FR-3).
   Follow AGENTS.md, docs/CODING_STANDARDS.md, docs/API_SPEC.md and docs/UI_UX_SPEC.md (Task list screen).
   Only touch: src/app/(app)/tasks/*, src/server/tasks/*, tests/tasks/*.
   Validate input with the existing schema helpers. workspace_id comes from the membership lookup.
   Done when: the FR-3 acceptance criteria pass as integration tests, the list shows empty and error states, and lint, typecheck, tests and build pass. Show the command output.

10. 10. Verification and review

    Agent report: 4 files changed, 2 test files added.
      npm run lint        exit 0
      npm run typecheck   exit 0
      npm test            38 passed, 0 failed, 0 skipped
      npm run build       exit 0
    You: read the diff, try it in the browser, and check that a second workspace can't see the task.
    Fresh review session: one finding (missing max length on the client) fixed in a follow-up commit.
    Handoff: T-04 marked done in TASKS.md; next is T-05.