Skip to content

Instantly share code, notes, and snippets.

@svngoku

svngoku/AGENTS.md

Last active January 6, 2026 19:31
Show Gist options

  • Select an option

    Learn more about clone URLs
  • Save svngoku/2312f9c3110ecf4788742671b2df4724 to your computer and use it in GitHub Desktop.

Select an option

Learn more about clone URLs
Save svngoku/2312f9c3110ecf4788742671b2df4724 to your computer and use it in GitHub Desktop.
Download ZIP
Raw
AGENTS.md

AGENTS.md

Single source of truth for onboarding coding agents to this repository. This file is included in every agentic coding session; follow it strictly where applicable.

1. Project purpose (WHY)

  • This repository exists to: SHORT ONE-LINER ABOUT THE PRODUCT / SERVICE.
  • Primary users: WHO USES IT and WHAT PROBLEM IT SOLVES.
  • Non-goals: WHAT THIS PROJECT DOES NOT TRY TO DO (keep it short and opinionated).

When proposing changes, prefer solutions that improve this core purpose rather than adding unrelated features.

2. Codebase map (WHAT)

2.1 Tech stack

  • Language(s): e.g., TypeScript, Python, Go.
  • Runtime: e.g., Node.js + Bun, Deno, Python 3.11.
  • Frameworks: e.g., Next.js, FastAPI, Express, Nest, Django.
  • Data layer: e.g., Postgres + Prisma, Redis, ClickHouse, Elastic.
  • Infrastructure: e.g., Docker, Kubernetes, Railway, Fly, Vercel, Cloud Functions.

2.2 Repository layout

Adapt this section to your actual structure.

  • apps/
    • web/ – Frontend app description.
    • api/ – Backend / API description.
  • packages/
    • core/ – Shared domain logic (entities, use-cases).
    • ui/ – Shared UI components.
    • agent/ – Agent tools, prompts, and harness integrations.
  • infra/
    • terraform/ – Infra as code description.
    • k8s/ – Deployment manifests / helm charts.
  • agent_docs/ – Task- and domain-specific docs for agents (see Section 4).

If you need to understand a feature, look first at:

  1. The relevant app in apps/.
  2. The domain logic in packages/core/.
  3. Any related docs under agent_docs/.

3. How the agent should work (HOW)

3.1 General behavior

These rules apply in every coding session, regardless of task type:

  1. Clarify the task.

    • Restate the user’s goal in your own words.
    • Identify the likely code areas and files you need to inspect.

  2. Read before writing.

    • Inspect existing implementations, tests, and docs before adding new ones.
    • Prefer following existing patterns over introducing new ones without a strong reason.

  3. Work incrementally.

    • Propose a short plan (1–5 steps) before large changes.
    • Implement changes in focused, coherent commits or diff chunks.

  4. Prefer minimal, safe edits.

    • Modify only what is required for the task.
    • Avoid large refactors unless explicitly requested or clearly necessary.

  5. Preserve public contracts.

    • Do not change public APIs (HTTP routes, exported functions, DB schemas) without calling this out explicitly and updating relevant docs/tests.

  6. Ask for missing context.

    • If required files or configurations are not visible, say what you need and how you would use it.
    • Do not guess secrets, credentials, or environment values.

  7. Use tools instead of guessing.

    • When available, use search, code navigation, test runners, linters, and type-checkers rather than inferring behavior from memory.

  8. Explain non-obvious choices.

    • For complex logic or architectural decisions, add brief comments or docstrings explaining why a particular approach was chosen.

  9. Be explicit about uncertainty.

    • If you are not certain about behavior or side effects, state your assumptions clearly and suggest how to verify them.

  10. Never invent data or secrets.

    • Do not hard-code secrets, API keys, or private tokens.
    • Use configuration/environment mechanisms already present in the repo.

3.2 Tooling and commands

This file intentionally avoids listing every command.
Instead, use these entry points and delegate details to task-specific docs:

  • Issue tracking (bd CLI)
    • Always initialize bd at the start of the session: bd onboard. If bd is not available, ask to install/enable it before proceeding.
    • Prefer working against a bd issue ID. If none is provided, use bd ready to find available work (or ask the user which issue to take).
    • Keep status up to date: bd update <id> --status in_progress and bd close <id> when done.
    • Before pushing changes, run bd sync.
  • Build & run
    • See agent_docs/building_the_project.md for how to build, run, and debug each app.
  • Tests & coverage
    • See agent_docs/running_tests.md for test commands, coverage, and performance test info.
  • Migrations & data
    • See agent_docs/database_schema.md for schema layout and migration workflow.
  • Architecture & boundaries
    • See agent_docs/service_architecture.md and agent_docs/service_communication_patterns.md.

If you need a command that is not obvious from package.json, Makefile, or these docs, explain what you would run and why, then ask for confirmation.

3.3 Style, linting, and formatting

  • Do not implement your own style rules from scratch.
  • Always assume the formatter and linter are the source of truth.
  • When you see lint or format errors:
    • Fix only what the tooling reports or what is clearly inconsistent with nearby code.
    • Do not mass-rewrite the codebase to a new style unless explicitly asked.

If the user provides linter/formatter output, prioritize fixing those issues before further feature work.

4. Progressive disclosure: agent docs index

These docs are not automatically included in every session.
When needed, ask to open or read them and then apply the relevant instructions.

Suggested structure (adapt as needed):

  • agent_docs/building_the_project.md
    • How to build, run, and debug each service/app.
  • agent_docs/running_tests.md
    • How to run unit, integration, and end-to-end tests; how to interpret failures.
  • agent_docs/code_conventions.md
    • Naming conventions, module boundaries, error-handling patterns, logging practices.
  • agent_docs/service_architecture.md
    • High-level overview of services, domains, and data flow.
  • agent_docs/database_schema.md
    • Key tables/collections, relationships, and migration policies.
  • agent_docs/service_communication_patterns.md
    • How services talk to each other (HTTP/gRPC/events), timeouts, retries, idempotency.

When starting a task, decide which (if any) of these docs are relevant.
If a doc is relevant, ask to read it before you start large changes.

5. Safety and constraints

These rules are non-negotiable in all tasks:

  • Do not delete or modify secrets, .env* files, or credential material.
  • Do not introduce commands that can destroy data (e.g., dropping databases) unless explicitly requested and clearly documented.
  • Do not change CI/CD configuration, deployment manifests, or infrastructure unless the task explicitly targets them.
  • Keep changes reversible and localized; avoid cross-cutting edits without a compelling reason and explicit sign-off.
  • If a task appears to conflict with these constraints, stop and ask for clarification.

6. When you are done

At the end of a task, provide:

  1. A brief summary of what you changed and why.
  2. A list of files touched.
  3. How to validate the changes (commands to run, URLs to hit, or tests to execute).
  4. Any follow-up tasks or risks worth tracking.

This helps the human operator quickly review, run, and ship your changes.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment