# AI agents and the guide

> alice guide, alice agents, AGENTS.md and CLAUDE.md in new projects, and alice explain: how AI coding agents learn and check Alice.

Canonical: https://alice-lang.org/documentation/tools/ai-agents/

[Documentation index](https://alice-lang.org/documentation/llms.txt) · [Complete book](https://alice-lang.org/llms-full.txt)

Alice ships its guide inside the CLI, so an AI agent (or a person) always reads the guide for the installed
version. New projects come with the files agents look for.

## The guide

| Command                   | Prints                                                         |
| ------------------------- | -------------------------------------------------------------- |
| `alice guide`             | the language, start here                                       |
| `alice guide performance` | ownership, forks, parallel loops, and when each is worth using |
| `alice guide proofs`      | `RULES.al`, `PROOF.al`, `alice prove`                          |
| `alice guide interop`     | .NET, C libraries, `@[Native]`, `safe`                         |

The guide is plain Markdown on stdout, in English, and every code example in it is compiled by Alice's tests.

## AGENTS.md and CLAUDE.md

`alice new` writes:

- `AGENTS.md` with an Alice block: run `alice guide`, check with `alice check`, run `alice prove --check` before
  committing, and a table of Ruby and Crystal habits that are wrong in Alice (arrays are fixed-size, a missing
  hash key raises, integers overflow with an error, generics use parentheses, packages come from NuGet).
- `CLAUDE.md` containing `@AGENTS.md`, so Claude Code reads the same file. There is one source and nothing to
  keep in sync.

In an existing project, `alice agents --write` adds or updates the block between `<!-- alice:start -->` and
`<!-- alice:end -->`, keeping the rest of your `AGENTS.md`, and creates `CLAUDE.md` if it is missing.
`alice agents` alone prints the block.

## Checking what the compiler did

`alice explain file.al` lists, per method, the optimizations applied: fork/join, parallel loops, owned arrays,
in-place maps, shared objects, stack arrays, SIMD and fast native calls. An agent changing hot code can confirm
it did not lose one.

## Continue reading

- Previous: [The interactive REPL](https://alice-lang.org/documentation/tools/repl.md)
- Next: [Toolchains and updates](https://alice-lang.org/documentation/tools/toolchains.md)