Project Instructions (AGENTS.md)

Project instruction files are how you teach the agent the rules of your codebase. When BharatCode starts a session it looks for AGENTS.md and CLAUDE.md files, reads them, and injects their contents into the system prompt. From that point on the agent treats them as standing orders: it builds with the command you specified, matches your style, and stays out of the directories you marked off-limits.

Both filenames are recognized, so a file written for another compatible agent works here unchanged — there is nothing BharatCode-specific you have to add.

How files are discovered

BharatCode collects instruction files along a chain that runs from the broadest scope down to the narrowest:

1. Global — your personal, machine-wide instructions that apply to every project.
2. Repository root — the AGENTS.md / CLAUDE.md at the top of the project.
3. Nested directories — any instruction files in subdirectories on the path down to your current working directory.

The chain is walked root-first: global, then the repository root, then each nested directory in turn, ending at your cwd. Every file found along that path is included — they accumulate rather than replace one another.

How the files combine

The collected files are concatenated root-first: the broadest instructions are placed at the top of the system prompt and the most-local file last. Because the deepest, most-specific file comes last, it overrides anything more general before it. In short: on a conflict, the most-local instruction wins.

[ global instructions          ]   loaded first  (broadest)[ myrepo/AGENTS.md             ]   repo root[ myrepo/packages/api/AGENTS.md]   loaded last   (most specific — wins)

The byte cap

The combined instruction text is byte-capped before it goes into the system prompt, so an enormous or runaway file can't crowd out your actual prompt and the model's working context. Keep these files focused on durable conventions — the commands, boundaries, and style rules the agent needs every time — rather than long prose. If you have a lot to say, prefer a short root file plus tighter nested files over one giant document.

An example AGENTS.md

A good instruction file is short and concrete. State the exact build and test commands, the style rules that matter, and anything the agent must never touch. Here is a repository-root AGENTS.md for a Go project:

# Project conventions This is a Go monorepo. Follow these house rules. ## Build & test- Build with: go build ./...- Run the full test suite with: go test ./...- Never commit if go vet ./... reports anything. ## Style- Use the standard library before reaching for a dependency.- Keep functions small; return errors, don't panic.- Run gofmt on every file you touch. ## Boundaries- Do not edit anything under vendor/ or generated/.- Keep all secrets in environment variables, never in code.

With this in place you no longer have to remind the agent how to run the tests or that vendor/ is off-limits — it reads the rules at the start of every session and applies them on its own.

Nesting and override in practice

Nesting lets each part of a monorepo carry its own rules while still inheriting the repository-wide ones. Consider this layout, where the API package adds conventions of its own:

myrepo/├── AGENTS.md            # repo-root: applies everywhere├── go.mod├── cmd/│   └── server/└── packages/    ├── web/    └── api/        ├── AGENTS.md    # applies only inside packages/api/        └── handler.go

The package-level file only needs to describe what is different about that corner of the codebase:

# packages/api conventions This service is the only place we use a database. ## Style- Use sqlc for queries; do NOT hand-write SQL strings.- Every handler returns a typed error, mapped to an HTTP status. ## Testing- Integration tests need Postgres; run them with: make test-api

Now the scope of each file follows where you are working:

• Working in cmd/server/, the agent sees the global instructions plus the repo-root AGENTS.md. The API-specific rules are not on the path to your cwd, so they are not loaded.
• Working in packages/api/, the agent sees both files: the repo-root AGENTS.md first, then packages/api/AGENTS.md last. It inherits the repo-wide rules (build with go build ./..., never edit vendor/) and layers the API rules on top (use sqlc, run integration tests with make test-api).
• Where the two genuinely disagree, the nested file wins because it is read last. If the root file said "keep handlers minimal" and the API file added "every handler returns a typed error," the agent honors the more specific, local instruction inside packages/api/.

Project instructions pair naturally with the rest of your configuration: config files set how BharatCode runs, while AGENTS.md tells the agent how to behave inside your code.