# Preparing code for AI agents: context, rules and test environments > Prepare a repository for AI agents with clear instructions, AGENTS.md, architecture context, safe test data and reproducible checks. Source: https://i8.ro/en/blog/preparing-code-for-ai-agents-context-rules-and-test-environments **Series II: From infrastructure to agentic projects in production. Episode 07 of 20.** In the previous episode, we turned a feature objective into verifiable tasks. The next problem appears immediately: even a good task fails when the agent does not know how to start the project, which rules apply or which command proves that the change works. The main decision is to treat the repository as the project's executable context package. Instructions, commands, decisions and test data should be kept close to the code, versioned and verified. A long document sent separately does not compensate for a project that starts only on one person's laptop. ## A repository is more than code A **repository** is the versioned space in which a team stores code and change history. For development with AI agents, it should quickly answer a few questions: what does the system do, how is it installed, how is it run, what must not be changed and how do we verify the result? In our hypothetical scenario, the B2B portal repository contains the web interface, requests API, document service and tests. The development agent receives a task to validate PDF uploads. The agent later integrated into the portal, which might classify documents, is a separate product feature. It does not read development instructions or receive repository access. A minimal package can have this structure: \`\`\`text README.md AGENTS.md docs/architecture/ docs/adr/ scripts/bootstrap scripts/check tests/fixtures/ .env.example \`\`\` The exact names may differ. What matters is that the team has one official startup path and one verification path, not five contradictory variants hidden in messages. ## README for orientation, AGENTS.md for execution The README remains the introduction for people: the project's purpose, main components, requirements and startup path. **AGENTS.md** is a Markdown file dedicated to instructions for coding agents. The open format describes it as a README for agents and recommends including installation and test commands, conventions and security considerations. For the portal, AGENTS.md should state concisely: - which directories contain the interface, API and document service; - the official commands for installation, startup, formatting, analysis and testing; - important versions of runtimes and package managers; - code conventions and where tests should be added; - sensitive areas such as migrations, authorization and document storage; - mandatory checks before handing over a change; - when the agent should stop and request a decision. In a monorepo, AGENTS.md files may exist closer to individual subprojects. The format documentation and GitHub state that the instructions nearest to the edited file take precedence. This rule should be tested in the chosen tool because support differs between products and features. Instructions are not an authorization mechanism. The phrase “do not access production” can guide the agent, but real isolation comes from absent credentials, minimum permissions, separate networks and technical approvals. A Markdown file does not stop a command allowed by the execution environment. ## One verified startup path GitHub recommends documenting the sequences for bootstrap, build, test, run and lint, including versions and preconditions, and actually trying the commands. For a small team, the practical solution is to provide two stable entry points: - `scripts/bootstrap`, which installs or verifies dependencies and prepares the local environment; - `scripts/check`, which runs mandatory checks in the team's accepted order. These scripts can call existing tools. They should not hide errors or continue after a critical step has failed. The agent and a new colleague use the same path, while continuous integration can call the same verification. A development container can describe the tools and settings of a containerized environment in a `devcontainer.json` file. The Dev Container Specification aims for consistency between local development and build and test automation. It is an option, not a requirement. For a simple project, pinned versions and reproducible scripts may be enough. For multiple services, the container can reduce differences between laptops, but it cannot by itself guarantee reproducibility of every external service. ## Safe test data and example configuration The `.env.example` file lists required keys with fictional values or explanations, never with real secrets. Tokens and passwords are injected by the authorized environment. Tests use synthetic accounts and documents, not uncontrolled copies from production. For the PDF capability, we keep small fixtures: a valid file, an oversized file, one with an incorrect declared type and metadata for fictional users. A **fixture** is a stable dataset prepared for a test. We document who updates it and what it verifies. If an example contains personal data, we replace it rather than “anonymizing” it superficially and publishing it in the repository. The agent should be able to create the local database from scratch and run tests without access to customer accounts. Every external service dependency has a controlled alternative: an official sandbox, emulator, mock or an explicit step that stops execution. The inability to contact production then becomes a property of the environment, not a request in a prompt. ## ADR: why a decision exists An **ADR**, or Architecture Decision Record, is a short record of an architectural decision. Michael Nygard's proposed model includes context, decision, status and consequences. If a choice changes, the old ADR remains in the history and is marked as superseded. For the portal, an ADR can explain why documents are stored in object storage, why the database keeps only the reference and which trade-offs result. The agent can then see the reason, not only the current shape of the code. AGENTS.md says how we work now; the ADR explains why an important choice exists. Neither should become a duplicate of the other. ## Verification in a clean environment Before considering the repository ready, we test it as a new colleague would: 1. clone it into an environment without caches or hidden local files; 2. run the bootstrap instructions exactly as written; 3. start services with example configuration and synthetic data; 4. execute the full verification and an end-to-end scenario; 5. correct the documentation or automation, not the memory of the person who intervened. The SWE-agent paper published at NeurIPS 2024 shows that the interface through which an agent navigates a repository and executes tests affects its behaviour and performance. Results from a research system do not promise the same performance in a commercial project. They do support a cautious conclusion: the environment and tools provided to the agent are part of the system being evaluated. The piece added to the project is the minimal context package: README for orientation, AGENTS.md for execution, ADRs for rationale, bootstrap and verification scripts, and synthetic fixtures. We review it in the same pull request as the code change that makes it inaccurate. In the next episode, we will compare where the agent can work: IDE, terminal and cloud environment. ## Sources - [AGENTS.md, open format for agent instructions](https://agents.md/), for structure, scope and instruction precedence, checked on October 9, 2026. - [GitHub Docs, *Adding repository custom instructions for GitHub Copilot*](https://docs.github.com/en/enterprise-cloud@latest/copilot/how-tos/copilot-on-github/customize-copilot/add-custom-instructions/add-repository-instructions), for repository context and build, test and validation commands. - [Development Containers, *Overview*](https://containers.dev/overview), for development environments and their reuse in build and test. - [Nygard, *Documenting Architecture Decisions*](https://cognitect.com/blog/2011/11/15/documenting-architecture-decisions) and [Yang et al., *SWE-agent*, NeurIPS 2024](https://proceedings.neurips.cc/paper_files/paper/2024/hash/5a7c947568c1b1328ccc5230172e1e7c-Abstract-Conference.html), for ADRs and the role of the agent interface. ## Next step Want to prepare an existing project for development assisted by AI agents? [Talk with the i8 team](https://i8.ro/en/contact).