> ## Documentation Index
> Fetch the complete documentation index at: https://docs.edgespark.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# AGENTS.md reference for EdgeSpark

> How AI agents should read the AGENTS.md (or CLAUDE.md / GEMINI.md) file in EdgeSpark projects and follow its instructions.

Every EdgeSpark project contains an agent instructions file. This file is the primary source of project-specific rules that take precedence over general EdgeSpark documentation.

## The agent file

When you run `edgespark init`, the CLI writes an agent instructions file based on the `--agent` flag:

| Flag                       | File written | Use with                                                                                                                                |
| -------------------------- | ------------ | --------------------------------------------------------------------------------------------------------------------------------------- |
| `--agent claude`           | `CLAUDE.md`  | Claude Code                                                                                                                             |
| `--agent gemini`           | `GEMINI.md`  | Gemini CLI                                                                                                                              |
| `--agent codex`            | `AGENTS.md`  | OpenAI Codex                                                                                                                            |
| `--agent <any other name>` | `AGENTS.md`  | GitHub Copilot, Cursor, OpenCode, Amp, Devin, Aider, Windsurf, Cline, Continue, Antigravity, Kiro, and all other AGENTS.md-based agents |

`--agent` is required. Known special cases are `claude`, `gemini`, and `codex`. Every other public agent name currently falls back to `AGENTS.md`, including `copilot`, `cursor`, `opencode`, `amp`, `devin`, `aider`, `windsurf`, `cline`, `continue`, `antigravity`, `kiro`, and your own custom agent name.

```bash theme={null}
edgespark init my-app --agent claude
# Writes CLAUDE.md to my-app/
```

## What the file contains

The generated agent file gives you everything you need to start writing code immediately:

* **Files to read before coding** — the exact paths to read before writing any route or query
* **Project structure** — where code goes, what is auto-generated, what to never edit
* **Rules** — specific do's and don'ts for this platform (batching, storage patterns, type safety)
* **Code examples** — minimal working patterns for database, storage, and auth
* **CLI usage** — how to pull schema, deploy, and handle auth

## Read it first

When starting on an EdgeSpark project, read the agent file before anything else — before reading the source code, before running any command.

The file tells you:

1. What files to read next (`server/src/__generated__/server-types.d.ts`, `server/src/defs/db_schema.ts`, etc.)
2. What the project structure looks like
3. What rules apply specifically to this project

## Project-specific additions

Project owners may append their own instructions below the generated content. These additions describe:

* Which routes already exist and what they do
* Coding conventions for this specific project
* Business rules that affect how data should be written or validated
* Which features are in progress vs. complete

Owner additions always appear below a visible separator. Follow them with the same priority as the generated content.

## Instructions file vs. this documentation

| This documentation        | The agent file                    |
| ------------------------- | --------------------------------- |
| General platform behavior | Project-specific rules            |
| How EdgeSpark works       | What this project needs           |
| Available APIs            | What has already been built       |
| Platform limits           | Owner preferences and conventions |

When there is a conflict, the agent file wins. The project owner may have intentionally restricted or extended the defaults.

## See also

<Columns cols={2}>
  <Card title="Supported agents" icon="robot" href="/agents/supported-agents">
    Which agents are supported and links to per-agent setup — plugins, extensions, skills.
  </Card>

  <Card title="Declarative workflow" icon="database" href="/agents/declarative-workflow">
    The core workflow for pulling schema and writing code against generated types.
  </Card>

  <Card title="The harness model" icon="shield" href="/agents/harness">
    Platform-level constraints that apply to every project regardless of agent file.
  </Card>

  <Card title="Claude Code" icon="code" href="/agents/claude-code">
    Claude Code plugin setup and how to extend CLAUDE.md.
  </Card>
</Columns>