1.6 AI-Native Repository Tour

What makes a repository "AI-native"? In this section, we'll explore the Emerald Grove Pet Clinic codebase to understand the patterns and structures that optimize a project for AI-assisted development.

The AI-Native Difference

A traditional repository is organized for human developers. An AI-native repository adds structures that help AI assistants:

Get an overview quickly — Without reading every file
Follow established patterns — Maintain consistency with existing code
Verify their work — Through comprehensive test suites
Stay within bounds — Via documented constraints and standards

Let's explore each component.

AGENTS.md: The AI Context File

The most important AI-native artifact is the agent context file — a Markdown file at the repository root that gives AI coding assistants project-specific knowledge.

The Open Standard: AGENTS.md

AGENTS.md is an open, vendor-neutral standard governed by the Agentic AI Foundation under the Linux Foundation. Before it existed, every AI tool invented its own format — CLAUDE.md for Claude Code, .cursor/rules/ for Cursor, .github/copilot-instructions.md for Copilot, and so on. Maintaining duplicate instructions across tools was a maintenance nightmare.

AGENTS.md solves this by providing a single file that any compatible AI agent reads automatically. It is natively supported by OpenAI Codex, Google Jules, Cursor, GitHub Copilot, Zed, Devin, and many others.

Claude Code does not yet support AGENTS.md natively (tracking issue). Until it does, the recommended approach is:

Write your instructions in AGENTS.md — this is the source of truth
Create a CLAUDE.md symlink — so Claude Code picks up the same content

# In your repo root:
ln -s AGENTS.md CLAUDE.md

Context markers as a lightweight compliance check

Some teams add a required marker at the start of every agent response — for example, a specific emoji in AGENTS.md. This gives you a quick visual check that the agent actually loaded and is following the instruction file.

Starting from Scratch

If you're working in Claude Code and there is no existing AGENTS.md or CLAUDE.md, bootstrap one with the /init slash command. It analyzes your codebase and generates a starter context file. The output is plain standard Markdown — no Claude-specific syntax — so you can safely rename it and symlink:

# Inside Claude Code, run:  /init
# Then in your terminal:
mv CLAUDE.md AGENTS.md
ln -s AGENTS.md CLAUDE.md

This gives you a solid starting point to refine. If you want the file to work across all AI tools, be mindful of tool-specific syntax — see the note below on file imports.

File Imports: Why They Matter and Where They Stand

As your project grows, you'll want your AGENTS.md to reference other files — architecture docs, coding standards, spec templates. How you reference them determines whether your AI agent actually sees that content.

The key distinction: Tools that support file imports (like Claude Code's @path/to/file syntax) will automatically load the referenced files into the agent's context window at the start of every session. The agent sees those files as if they were part of the context file itself. Tools that don't support imports treat the @ reference as plain text — the agent never receives those files unless it discovers them on its own during exploration.

This matters more than it might seem. If you add @docs/architecture.md to your context file expecting your agent to follow your architecture guidelines, but your tool doesn't support imports, the agent is working without that context entirely. You may not realize the gap until inconsistent code starts appearing.

There is no cross-agent standard for file imports yet. The AGENTS.md specification has an open issue requesting import/reference support, but nothing has been formalized. Here's the current landscape:

Syntax	Supported By	Effect
`@path/to/file`	Claude Code, Cursor	Auto-imports file into agent context (Claude Code: recursive, max 5 hops)
Standard Markdown links	All tools, humans	Clickable link only — no auto-import
(no syntax)	Copilot, Windsurf, Codex, Aider	No import mechanism available

A pragmatic workaround some teams use is a dual-format approach — writing references as standard Markdown links while also including the @path so tools like Claude Code auto-import the content:

<!-- Claude Code auto-imports this; other tools see a normal link -->
See [coding standards](@docs/standards/coding.md) for style rules.

This isn't standardized anywhere, but it ensures the file is useful across tools: Claude Code gets the auto-import, and every other tool and human reader gets a navigable Markdown link. Since your CLAUDE.md is a symlink to AGENTS.md, both files benefit from a single change.

As the ecosystem matures, expect a formal import mechanism in the AGENTS.md spec. For now, choose the approach that fits your tooling: use @path imports if your team is primarily on Claude Code or Cursor, use the dual-format workaround for mixed environments, or stick to plain Markdown if broad portability is the priority — and accept that agents using tools without import support will need to discover referenced files on their own.

This is exactly what the Emerald Grove Pet Clinic repo does. Start by examining it:

Read the AGENTS.md file and summarize its key sections

An AGENTS.md file typically contains:

Project Overview

A concise description of what the project does, its architecture, and key technologies. This gives Claude immediate context without exploring the entire codebase.

Coding Standards

Rules and conventions the project follows:

Code style and formatting
Naming conventions
Testing requirements
Documentation expectations

Key Commands

Common operations Claude might need to run:

Build commands
Test commands
Linting commands
Deployment commands

Architecture Notes

High-level system design:

Directory structure
Component relationships
Data flow patterns

Things to Avoid

Explicit constraints:

Deprecated patterns
Security considerations
Known gotchas

Why AGENTS.md Matters

The agent context file is injected into the AI assistant's context at the start of every session. It's the most efficient way to give AI assistants project-specific knowledge without repeatedly explaining it. By using the open AGENTS.md standard, your instructions work across all supporting tools — not just one vendor.

Documentation Structure

Explore the documentation directory:

Show me the structure of the docs/ directory and explain what each part contains

AI-native repositories typically include:

docs/specs/

Where SDD artifacts live:

docs/specs/
├── 01-spec-upcoming-visits/
│   ├── 01-spec-upcoming-visits.md       # The specification
│   ├── 01-tasks-upcoming-visits.md      # Task breakdown
│   ├── 01-questions-1-upcoming-visits.md # Clarifying questions
│   ├── 01-proofs/                        # Proof artifacts
│   └── 01-validation-upcoming-visits.md  # Validation report

This structure provides Claude with examples of completed SDD workflows it can reference.

Architecture Documentation

System design documents that explain:

How components interact
Data models and relationships
Integration points
Deployment architecture

Standards and Guidelines

Documented conventions for:

Code style
Testing practices
Git workflow
Review process

In Emerald Grove Pet Clinic, you can see this documentation made concrete in files like:

File	Purpose
`docs/DEVELOPMENT.md`	TDD workflow, setup, and daily development process
`docs/TESTING.md`	Testing strategy and Playwright E2E guidance
`docs/ARCHITECTURE.md`	System design and technical decisions
`docs/PRECOMMIT.md`	Hook configuration, usage, and troubleshooting

Test Structure

Comprehensive tests are essential for AI-native development. Explore the test setup:

What testing frameworks does this project use? Show me examples of each test type.

Unit Tests

Fast, isolated tests for individual components:

Show me an example unit test from this project

Integration Tests

Tests that verify component interactions:

Show me an example integration test, particularly one that tests a controller

End-to-End Tests

Playwright tests that verify the full application:

Explore the e2e-tests directory and explain how the E2E tests are structured

E2E tests are particularly valuable because they:

Generate proof artifacts (screenshots, traces)
Verify user-facing behavior
Catch integration issues

Performance Tests

Apache JMeter load tests that simulate realistic user traffic against the full application:

Explore the src/test/jmeter directory and explain how the performance test plan is structured

Quality Gates

AI-native repos enforce quality through automation:

What CI/CD workflows does this project have? What checks do they run?

Look for:

Build verification — Does it compile?
Test execution — Do tests pass?
Linting — Does code meet style standards?
Security scanning — Are there vulnerabilities?

These gates provide immediate feedback on AI-generated code.

A useful AI-native principle shows up here: prefer deterministic guardrails over prompt-only instructions. An agent can miss or ignore a written reminder in AGENTS.md, but a failing pre-commit hook, CI job, or review bot enforces the rule automatically.

Emerald Grove Pet Clinic also layers in AI-assisted review with .coderabbit.yaml, so pull requests get another automated review pass in addition to local hooks and CI.

Repository Standards Files

Explore the configuration that enforces standards:

What configuration files enforce coding standards in this project?

Common files include:

File	Purpose
`.editorconfig`	Editor settings (indentation, line endings)
`.pre-commit-config.yaml`	Pre-commit hook definitions
`checkstyle.xml`	Java code style rules
`.prettierrc`	JavaScript/CSS formatting
`pom.xml` / `build.gradle`	Build configuration and plugins

Reproducible Development Environments

Another AI-native advantage is a predictable local environment. A .devcontainer/ directory gives agents and humans the same preconfigured toolchain instead of relying on each person to recreate setup by hand.

When you explore Emerald Grove Pet Clinic, check what its dev container pre-installs and how that reduces environment drift.

The .claude Directory

Some projects include project-specific Claude configuration:

Is there a .claude directory? What does it contain?

This may include:

Project-specific settings
Custom slash commands
MCP server configuration
Permission rules

Exploring with Sub-Agents

Claude Code can spawn specialized agents for exploration. Try:

Use an exploration agent to find all the REST API endpoints in this project

Or:

Use an exploration agent to understand how the database schema is structured

Sub-agents can perform thorough searches without bloating your main conversation context.

Claude Code has built-in subagents:

Explore, read-only codebase exploration and file discovery
Plan, research and produce a plan without editing
General-purpose, the default agent for most tasks

/agents typically shows your custom agents (project or user-defined). If you have not created any, it will say "no agents", even though the built-in ones still exist and can be used.

Patterns to Notice

As you explore, observe these AI-native patterns:

1. Explicit Over Implicit

AI-native repos document what human developers might "just know":

Environment setup steps
Required dependencies
Common workflows

2. Verification at Every Level

Multiple test types ensure AI-generated code can be validated:

Unit tests for logic
Integration tests for wiring
E2E tests for behavior

3. Structured Artifacts

Consistent file structures and naming conventions help Claude find things:

Predictable directory layouts
Descriptive file names
Clear separation of concerns

4. Context Anchors

Files like AGENTS.md and docs/architecture.md provide stable reference points that don't change frequently.

Exercise: Create Your Own Context Summary

Put your exploration skills to work:

Based on your exploration of this codebase, create a one-paragraph summary that would help a new AI assistant understand this project quickly.

Compare Claude's summary with the existing AGENTS.md to see how well the project is documented.

The meta-principle

The practices in an AI-native repo are not exotic new rules. Clear docs, strong tests, explicit standards, and reproducible environments are already signs of a well-engineered project. Optimizing for AI agents is often just another way of saying: make good engineering habits explicit and enforceable.

Next Steps

Now that you understand the structure of an AI-native repository, the final section in this introduction guides you through hands-on exploration exercises using Claude Code's full toolkit.

Knowledge Check

Question 1 of 8