froodx.net Experiments, notes, and selected publishing
Back to initiatives

AI-Agent Conventions

  • architecture
  • guide
  • ai-agents
  • workflow
  • safety

Canonical generic working rules for Claude Code, GitHub Copilot and future coding agents. These rules are deliberately repository- and vendor-light so they can be reused across internet, extranet, mobile and scripts repositories.

1. purpose

AI agents must make the codebase easier to understand, not merely make the current task pass.

Priorities:

  1. stay inside the correct repository/application boundary
  2. read the canonical rules before editing
  3. find code by well-named paths before searching widely
  4. change the smallest sensible surface
  5. preserve architecture and existing behaviour
  6. avoid unnecessary token/credit usage
  7. never infer permission for production or destructive actions

2. canonical documents

Every repository should expose:

docs/canonical/
├── ai-agent-conventions.md
├── coding-conventions.md
└── style-guide.md

Read:

  • ai-agent-conventions.md before agent-driven changes
  • coding-conventions.md before adding/moving code
  • style-guide.md before UI/layout/theme changes

The repository README.md should explain what the repository owns, how it runs and where these canonical documents live.

Do not duplicate canonical rules across multiple instruction files. Vendor bootstrap files should point to the canonical documents.

3. repository boundary first

Before editing, identify the owning repository and application.

Typical multi-repository workspace:

workspace/
├── internet/
├── extranet/
├── mobile/
├── scripts/
└── platform.code-workspace

Rules:

  • Default to editing only the repository named or clearly implied by the task.
  • Do not silently edit neighbouring repositories in a multi-root VS Code workspace.
  • Cross-repository changes require explicit task scope or a clearly documented dependency that makes them unavoidable.
  • If a task is frontend-only, do not change backend/database/deployment code to solve it.
  • If a task is backend-only, do not rewrite the frontend without need.
  • If a task concerns deployment scripts, do not modify application behaviour unless explicitly required.
  • Keep public-site, CMS, extranet and mobile responsibilities visibly separated.

This boundary rule is especially important for smaller/cheaper coding models.

4. standard application boundaries

Within a normal application repository:

front-end/     browser-facing code
back-end/      server/API/business/data code
mobile/        optional client applications
docs/          canonical rules and project documentation
scripts/       local development/deployment/maintenance scripts

Respect these boundaries.

Inside back-end/, FastAPI, business logic, SQLAlchemy, integrations and workers remain backend concerns unless there is a genuine independent deployment boundary.

5. filename is the index

The fastest search is no search.

  • Read a known, well-named path first.
  • Infer likely location from the standard scaffold and filenames.
  • Use targeted search when the path is uncertain.
  • Avoid repository-wide grep as a default discovery strategy.
  • Never read every file “just in case”.
  • Do not re-read content already present in the current context.
  • When creating files, choose names that make future discovery obvious.

The detailed naming rules live in coding-conventions.md.

6. token / credit efficiency

Treat context and tool calls as a limited engineering resource.

  • Read only what the task needs.
  • Prefer targeted file reads over broad searches.
  • Prefer small diffs over rewriting whole files.
  • Do not generate long explanations or reports unless requested.
  • Do not repeatedly summarise work already visible in the diff.
  • Do not create speculative architecture, layers, abstractions or documentation.
  • Do not load neighbouring applications merely because they are available in the workspace.
  • Stop exploring once enough evidence exists to make the requested change safely.

7. edit existing files first

Before creating a new file, ask:

  1. Does an existing file already own this concern?
  2. Would adding the code there violate one-concern or size rules?
  3. Is a new file actually clearer and easier to find?

Create a new file only when it has a distinct, well-named responsibility.

Never create duplicate plans, duplicate canonical docs, *-new.*, *-v2.* or temporary parallel implementations without explicit need.

8. split-first rule

If a touched source file is already over the 800-line hard limit, pause feature work and split it before adding more code unless the user explicitly directs otherwise.

Do not wait for 800 lines when the file clearly owns multiple unrelated concerns.

Markdown over 300 lines should be refactored into a short index plus well-named parts.

9. frontend work

For frontend changes:

  • follow docs/canonical/style-guide.md
  • reuse existing components and tokens before creating new ones
  • keep reusable components in front-end/src/components/
  • keep feature-specific UI in the owning front-end/src/features/<feature>/
  • keep styling in the established styles/tokens/theme files
  • do not solve framework styling issues by changing backend architecture
  • preserve direct routing/reload behaviour
  • preserve accessibility and control states

Determine whether the product surface is Workspace, Public site or Mobile before applying shell rules.

10. backend work

For backend changes:

  • keep the FastAPI entry point small
  • put business behaviour in the owning feature
  • keep shared SQLAlchemy engine/session infrastructure under back-end/app/db/
  • use Alembic for schema changes
  • never make an untracked database schema change
  • keep integrations/workers under backend unless they truly become independently deployed applications
  • preserve transaction, authentication, authorisation and audit behaviour already documented by the project

Read any project-specific database/security invariants before changing those areas.

11. Docker and infrastructure

Docker ownership:

  • application repository owns the Dockerfile that builds that application
  • Compose describes how multiple containers run together
  • a shared scripts/operations repository may own cross-repository deployment Compose files

Agent rules:

  • do not invent extra containers or services without a requirement
  • prefer existing Dockerfiles/Compose configuration
  • keep the official PostgreSQL image unless customisation is genuinely needed
  • do not move Dockerfiles to a central folder merely for neatness
  • do not add GitHub Actions, Cloudflare Workers or other CI/CD systems unless explicitly requested

12. deployment model

Default assumption for this project family:

  • development occurs locally
  • GitHub is source control
  • deployment is performed through local scripts
  • public static sites may deploy to Cloudflare Pages
  • server applications may deploy as Docker containers to AWS Lightsail

These are defaults, not permission.

Never deploy, restart production, modify production infrastructure, rotate secrets, run destructive database operations or push live changes without explicit user authorisation.

Access is not authorisation.

13. scripts and shell commands

  • Prefer existing scripts over reconstructing deployment/build commands manually.
  • Read a deployment/destructive script before running it.
  • Do not add destructive flags such as --delete, forced resets or schema drops casually.
  • Preserve .env, certificates, persistent volumes and database data.
  • Avoid shell one-liners that make broad unreviewed edits when a structured edit is safer.

14. Git rules

  • GitHub is source control unless the repository explicitly documents another role.
  • Do not assume GitHub Actions exists or should exist.
  • Never commit .env, secrets, .venv/, node_modules/, build caches or generated local state.
  • Keep commits scoped to the task.
  • Do not rewrite unrelated history.
  • Do not force-push unless explicitly authorised.

15. multi-root VS Code workspaces

A multi-root workspace is a convenience layer, not a single codebase.

  • Treat each repository root as an independent ownership/security boundary.
  • Read the target repo’s README/canonical rules before editing it.
  • Do not assume one repo’s dependencies, environment or deployment rules apply to another.
  • Shared conventions may be kept consistent across repos, but code changes remain local unless the task explicitly spans repositories.
  • When a task spans repositories, state the planned repositories/files before editing.

16. virtual environments and dependencies

  • Use the .venv/ belonging to the Python application being changed.
  • Do not install backend dependencies globally.
  • Do not mix Python dependencies across independent applications.
  • Use the owning package.json for JavaScript dependencies.
  • Do not add dependencies to another application merely because it is open in the same workspace.

17. planning and checkpoints

For non-trivial work:

  • identify affected repository/application
  • identify relevant canonical/project-specific docs
  • identify likely files
  • make the smallest coherent change
  • test/verify
  • update the existing plan/handoff document if the project uses one

Do not create a new plan document when an active one already exists.

18. comments and documentation

  • Comments explain non-obvious why, not obvious what.
  • Update README/docs when architecture, paths, configuration or operational behaviour changes.
  • Do not create documentation solely to narrate the current task.
  • Keep canonical documents generic; put product-specific invariants in clearly named project documents.

19. verification before completion

Before marking a task complete:

  1. confirm only intended repositories/files changed
  2. run the relevant tests/checks
  3. check imports/routes/builds affected by moved code
  4. check no source file exceeds the hard size limit as a result
  5. confirm secrets/generated environments were not added
  6. confirm no deployment occurred unless explicitly authorised
  7. give a concise completion note rather than a long recap

20. vendor bootstrap guidance

Use vendor-supported bootstrap/instruction locations, but keep them short.

Their job is to tell the agent:

  1. what repository it is in
  2. where docs/canonical/ai-agent-conventions.md lives
  3. which project-specific architecture/invariant docs must be read for the current area

Do not copy the full conventions into each vendor bootstrap. One canonical source prevents drift.

21. project-specific rules

These generic conventions intentionally do not contain project-specific database schemas, table names, permission models, hosting certificates, business rules or deployment commands.

Each project may add narrowly scoped canonical/project documents for those invariants.

When a project-specific rule conflicts with this generic document, the more specific rule governs that project, but the exception should be explicit and documented.