SVRBC Developers

Appearance

Agents files ​

Coding agents (Claude Code, Codex, and others) read instructions from files in the repository. Every SVRBC repository has them, so that an agent knows the project’s conventions, and knows where the org-wide ones live, before it changes anything.

The rules ​

  1. Every repository has an AGENTS.md at its root. It’s the one file of instructions; agents that look for another name get a pointer to it.

  2. CLAUDE.md is a one-line pointer, because Claude Code reads that name:

    md
    See [AGENTS.md](./AGENTS.md) for instructions.

  3. Every AGENTS.md names this handbook as the source of defaults. Put this near the top:

    md
    ## Defaults

SVRBC’s org-wide practices, covering builds, CI, domains, tools and these
agent files, are at https://developers.svrbc.org
(source: https://gitlab.com/svrbc/developers.svrbc.org). Follow them unless
this file says otherwise; where it does, this file wins for this project.

  4. Write down only what’s specific to the project. Don’t copy the handbook into each repository, where copies drift. Link to the page instead. When a project departs from a default, say so and say why.

What belongs in a project’s AGENTS.md ​

  • What the project is, in a paragraph: what it serves, how it deploys, and where the moving parts live.
  • Conventions an agent would otherwise get wrong: typography, brand spellings, generated files that mustn’t be hand-edited, commands that must run after a change.
  • The reasons behind them. A rule with its reason gets applied sensibly to cases nobody anticipated.
  • Traps that already cost time, so the next agent doesn’t repeat them.

What doesn’t belong ​

  • Secrets. Many SVRBC repositories are public, and agent files are read by tools that may send them to a model provider.
  • Personal setup, such as one person’s paths, machines or accounts. That goes in the person’s own global agent instructions.
  • Anything already in this handbook. Link to it.

When a lesson applies org-wide ​

If an agent learns something that would help in every repository (a tool’s quirk, a service’s misleading error), add it here, not to one project’s AGENTS.md. The Domains page’s note on Porkbun’s INVALID_DOMAIN error started this way.