Vyriy

AGENTS.md as a Calm Contract for AI-Assisted Development

AI tools are becoming part of everyday software development. They can generate code, write tests, update documentation, refactor modules, explain errors, and help with design decisions.

But there is one important problem.

AI does not automatically know how your project thinks.

It can read files. It can follow patterns. It can infer intent. But inference is not the same as a stable engineering contract.

This is where AGENTS.md becomes useful.

It is not just another documentation file. It is a small guide for AI agents, coding assistants, and future contributors. It describes how the repository should be changed, what style of decisions is expected, and which principles matter more than cleverness.

For Vyriy, this fits naturally into the idea of calm architecture.

The Problem

Every project has hidden rules.

Some of them are technical:

  • how files are organized;
  • how public exports are managed;
  • how tests are written;
  • how packages are published;
  • how documentation is updated.

Some of them are cultural:

  • prefer simple code;
  • avoid unnecessary dependencies;
  • keep public APIs small;
  • do not refactor unrelated parts;
  • make changes easy to review.

Experienced developers often keep these rules in their heads. Teams slowly learn them through code reviews, mistakes, and repeated explanations.

AI agents do not have that history.

Without a clear guide, an agent may still produce working code, but it may also:

  • introduce a new abstraction too early;
  • export internal helpers;
  • place implementation logic in index.ts;
  • update code but forget tests;
  • update tests but forget README examples;
  • add dependencies where simple code would be better;
  • change unrelated files because it “looks cleaner”.

The result is not always broken code.

Sometimes the result is worse: code that works, but slowly makes the project harder to reason about.

AGENTS.md Is a Checklist

In high-risk fields, checklists are used not because people are inexperienced, but because even experts can miss simple steps.

Software has a similar problem.

A senior developer may know that every new public export should be tested and documented. But under pressure, even simple checks can be missed.

AI agents need the same kind of support.

AGENTS.md acts like a checklist for repository behavior. It does not replace code review. It improves the starting point before review even happens.

A good agent guide answers simple questions:

  • What kind of code belongs here?
  • What should be avoided?
  • Where should implementation logic live?
  • How should public APIs be exposed?
  • What tests are expected?
  • What documentation should be updated?
  • What should be checked before finishing?

This is especially useful in package-based systems, monorepos, component libraries, static sites, serverless projects, and internal tooling.

Why This Matters for Calm Architecture

Calm architecture is not only about infrastructure or deployment style.

It is also about reducing unnecessary mental load.

A calm project should be easy to understand, easy to change, and easy to recover when something goes wrong.

That means the project needs boring, stable rules:

  • small modules;
  • explicit boundaries;
  • predictable file shapes;
  • stable public APIs;
  • focused tests;
  • minimal hidden conventions;
  • documentation that matches reality.

AI can help with this, but only if it follows the same discipline.

Without guidance, AI may optimize for immediate output.

With AGENTS.md, AI can optimize for maintainable output.

That difference matters.

What Should Be in AGENTS.md?

The file does not need to be long. In fact, it should usually be short enough to read before making a change.

A practical structure looks like this:

# Project Agent Guide

## Core Principles

Describe the engineering style of the project.

## File Shape

Explain how files should be organized.

## Public Surface

Explain how exports and public APIs are managed.

## Tests

Explain what kind of tests are expected.

## Documentation

Explain what documentation must stay in sync.

## Components

Add UI-specific rules when the project contains React or other components.

## Change Discipline

Explain how to keep changes scoped and reviewable.

## Before Finishing

Add a final checklist.

This structure works well because it separates principles from concrete checks.

The principles guide decisions.

The checklist catches mistakes.

Example: Public Surface Rules

For a TypeScript package, one useful rule is:

Every new public export must be re-exported from `index.ts`.

This looks simple, but it prevents a common problem: adding useful code that is not actually part of the package API.

Another useful rule:

Keep `index.ts` as a public re-export surface only. Do not place implementation logic in it.

This keeps package entry points boring and predictable.

Boring entry points are good. They reduce surprises for both humans and tools.

Example: Tests

Tests should focus on public behavior, not private implementation details.

A good rule:

Cover public behavior and meaningful edge cases.
Prefer behavior-focused tests over private implementation lock-in.

This helps avoid fragile tests that break during harmless refactoring.

For packages, it is also useful to have a focused validation command:

yarn jest packages/<package> --runInBand --coverage=false

Or, when the package has its own workspace script:

yarn workspace <package-name> test --runInBand --coverage=false

The exact command is less important than the idea: after changing a package, validate that package directly.

Example: Documentation Sync

One common source of project drift is outdated documentation.

The code changes. The README stays the same.

An agent guide can make this explicit:

Sync implementation, tests, README, docs, and public re-exports together.

This tells the agent that a change is not complete just because the code compiles.

If the public behavior changed, examples and documentation may also need to change.

AGENTS.md Is Not Only for AI

Even though the name sounds AI-specific, the file is useful for humans too.

It is a compact engineering agreement.

New contributors can read it before making changes. Maintainers can use it during review. The project owner can use it to clarify expectations.

In small projects, it prevents personal rules from staying only in the author’s head.

In larger projects, it reduces repeated review comments.

For AI-assisted development, it becomes even more valuable because agents can read and apply it directly.

Keep It Universal, Then Specialize Locally

A good pattern is to keep a universal AGENTS.md at the project root and add more specific guidance only where needed.

For example:

AGENTS.md
packages/
  ui/
    AGENTS.md
  config/
    AGENTS.md
  server/
    AGENTS.md

The root file describes general project discipline.

Package-level files can add local details:

  • React component rules for UI packages;
  • Node.js runtime assumptions for server packages;
  • publishing rules for npm packages;
  • infrastructure rules for deployment packages.

This keeps the main guide reusable without making it too generic to be useful.

The Vyriy Angle

Vyriy is built around calm, explicit, reusable architecture.

That means an agent should not only generate code. It should preserve the shape of the system.

For Vyriy-style projects, AGENTS.md should encourage:

  • explicit module boundaries;
  • SSR-friendly and SSG-friendly code;
  • small typed public APIs;
  • low dependency pressure;
  • package-level reuse only after behavior is proven;
  • documentation that stays close to real usage;
  • changes that are easy to review.

The goal is not to make AI slower.

The goal is to make AI output calmer.

A Small File With a Large Effect

AGENTS.md is not magic.

It will not replace architecture, tests, review, or judgment.

But it gives AI agents a better map.

And when the map is clear, the generated code is more likely to fit the project instead of just solving the immediate prompt.

That is the practical value.

A calm project does not depend on everyone remembering every hidden rule.

It writes the important rules down.

Suggested Minimal AGENTS.md

Here is a compact starting point:

# Project Agent Guide

Keep changes calm, explicit, reusable, and easy to reason about.

## Core Principles

- Prefer simple modules over clever frameworks or hidden conventions.
- Keep boundaries explicit and avoid project-specific coupling.
- Extract only proven reusable behavior.
- Keep public APIs small, typed, documented, and stable.
- Prefer code that is easy to test, deploy, observe, and replace.

## File Shape

- Prefer one exported runtime method, component, or helper per production file when it stays readable.
- Prefer one matching test file per production file.
- Keep `index.ts` as a public re-export surface only.
- Keep constants near the code that owns them unless they are shared.

## Public Surface

- Every new public export must be re-exported from `index.ts`.
- Add or update public surface tests when exports change.
- Add JSDoc for public exports when behavior or usage expectations need explanation.
- Avoid exporting internal helpers only to make tests easier.

## Tests

- Cover public behavior and meaningful edge cases.
- Prefer behavior-focused tests over private implementation lock-in.
- Keep tests deterministic.
- Avoid real network, filesystem, timers, or browser dependencies unless required by the behavior.

## Documentation

- Keep README files concise and usage-oriented.
- Document real public exports, supported options, and working examples.
- Keep implementation, tests, examples, and documentation in sync.

## Change Discipline

- Keep changes scoped to the requested behavior.
- Avoid unrelated refactors and metadata churn.
- Do not introduce new dependencies unless they clearly reduce complexity.
- Prefer small, reviewable changes over broad rewrites.

## Before Finishing

- Public exports are updated.
- Tests are updated.
- Documentation examples still match the real API.
- No unrelated files were changed.

This is enough to start.

Over time, the guide can evolve with the project.

Like any good checklist, it should stay practical. If a rule does not help real work, remove it. If the same review comment appears again and again, add it.

That is calm maintenance.

Not more process.

Just fewer repeated mistakes.