Carson Ye

A Simple AGENTS.md Setup for Agent-Based Development

Published February 20, 2026

When working with agent-based development, one thing quickly becomes repetitive:

Every new project starts by telling the agent the same things again.

  • how to structure changes
  • how to write commits
  • how to open PRs
  • how to validate work
  • how to keep docs aligned

It works, but it’s a bit tedious.

After doing this across a few projects, I started looking for a simpler setup.

Separate Stable Rules from Project Context

The main idea is simple:

some instructions are global, some are project-specific

Instead of putting everything into each repo, I split it into two layers:

  • a global AGENTS.md for stable defaults
  • a repo-level AGENTS.md for project-specific constraints

This is not a strict rule or best practice — just a way to reduce repetition.

Global AGENTS.md

This file defines how I want the agent to work in general.

It’s mostly about workflow and habits, and rarely changes.

# Global AGENTS.md

## Working Style
- Prefer small, reviewable changes.
- Do not mix unrelated refactors into a focused task.
- Prefer the simplest solution that satisfies the request.
- Read relevant existing docs and nearby code before changing structure or behavior.
- If docs and code disagree, do not silently diverge; call it out and update docs when appropriate.

## Planning
- For non-trivial tasks, plan briefly before coding.
- State assumptions clearly when something is uncertain.
- Prefer concrete edits, commands, and file paths over generic advice.

## Code Quality
- Optimize for readability and maintainability over cleverness.
- Keep responsibilities separated; avoid mixing unrelated concerns in one module.
- Do not introduce new dependencies without a clear reason.
- Avoid vague names like `helper`, `common`, `misc`, or `stuff`.

## Validation
- Validate locally before opening a PR whenever feasible.
- If behavior changes, add or update tests when the repo already has a testing pattern.
- At minimum, verify the changed path works and does not obviously break adjacent behavior.

## Git Workflow
- Never push directly to `main`.
- Create a feature branch from `main`.
- Use `gh` to open a normal PR, not a draft PR.
- Keep PRs focused and clearly titled.

## Commit Convention
- Use Conventional Commits.
- Prefer `type(scope): subject` when helpful.
- Keep the subject imperative, concise, and without a trailing period.

## Pull Requests
- PR descriptions should include:
  - Summary
  - Changes
  - Risk / Rollback
  - Notes / Follow-ups
- Include a short validation note for non-trivial changes.
- Include screenshots for UI changes when useful.

## Documentation
- Keep documentation aligned with implementation.
- If a change affects setup, architecture, API shape, workflows, or behavior, update the relevant docs in the same PR.
- Keep AGENTS.md concise; move task-specific or deep project detail into docs.

## Guardrails
- Do not commit secrets, tokens, or private credentials.
- Do not add unnecessary complexity, infrastructure, or platform concerns unless requested.

Repo-Level AGENTS.md Template

Each repo still needs its own AGENTS.md, but this one focuses only on the project itself.

I keep it as a template and fill it in when starting a new project.

# AGENTS.md

## Project Summary
<!--
Describe:
- what this repository is
- what it is not
- who it is for
- what success looks like
Keep this short and concrete.
-->

## Tech Stack
<!--
List the actual stack:
framework, language, key libraries, runtime, package manager, deployment.
Avoid vague descriptions.
-->

## Commands
<!--
Provide real commands the agent can run.
Only include commands that actually exist.
-->

- Install:
- Dev:
- Build:
- Test:
- Lint:
- Typecheck:

## Repository Layout
<!--
Explain only important directories and responsibilities.
Focus on areas likely to be modified or misunderstood.
-->

## Project Rules
<!--
Project-specific constraints only.
Examples:
- architecture boundaries
- domain logic constraints
- performance limits
- compliance rules
- UI constraints
-->

## Non-Goals
<!--
Explicitly define what should NOT be built.
This helps avoid unnecessary complexity.
-->

## Documentation Priority

Read these before making major changes:
1. AGENTS.md
2. docs/architecture.md
3. docs/implementation-plan.md

If docs and code conflict:
- do not silently diverge
- update docs in the same PR when needed

## Conventions
<!--
Only include conventions that matter in this repo.
-->

## Validation

Before opening a PR, validate:
- build passes
- relevant tests pass
- changed flow works
- docs updated if needed

## Definition of Done
<!--
Define what “done” means for this repository.
-->

Closing Thought

This is not a universal pattern.

Different workflows will naturally lead to different setups.

For me, separating global behavior from project context made things simpler:

  • less repetition
  • smaller files
  • easier to start new projects

If you’re also repeating the same instructions across repositories, this might be worth trying.

Otherwise, feel free to ignore it.

Keep Reading

Comments