> ## Documentation Index
> Fetch the complete documentation index at: https://docs.codealive.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Instructing Coding Agents
> How to make Claude Code, Cursor, and Codex actually use CodeAlive tools instead of their built-in search
## Why instructions matter
Connecting the [CodeAlive MCP server](/integrations/mcp) gives an agent new tools — it does not change the agent's habits. Coding agents ship with built-in exploration tools (Cursor's `codebase_search`, Claude Code's `Grep`/`Glob`, Codex's shell search), and their planners reach for those first. Without an explicit instruction, an agent will happily run local grep over one checkout while a fully indexed, cross-repository semantic engine sits unused.
The fix is a short instruction file in the agent's native format. This page covers the patterns that reliably work and where to put them for each agent.
Working with 1C:Enterprise (BSL) codebases? Read the dedicated page — [CodeAlive & 1С](/guides/1c-agents) — first: the word "metadata" means something different in 1C, and agent instructions need to account for it.
## Where instructions live
| Agent | Instruction file | Notes |
| ----------------------- | ------------------------------------------------------- | --------------------------------------------------------------------------------- |
| Claude Code | `CLAUDE.md` (repo root or `~/.claude/CLAUDE.md`) | Also reads `AGENTS.md`. See [Claude Code setup](/integrations/mcp/claude-code) |
| Codex (CLI / App / IDE) | `AGENTS.md` (repo root) + `~/.codex/AGENTS.md` (global) | See [Codex setup](/integrations/mcp/codex) |
| Cursor | `.cursor/rules/*.mdc` | Legacy `.cursorrules` is deprecated. See [Cursor setup](/integrations/mcp/cursor) |
| Cline | `.cline/rules.md` | See [Cline setup](/integrations/mcp/cline) |
| Most other agents | `AGENTS.md` (repo root) | `AGENTS.md` has become a de-facto cross-agent standard |
Because Claude Code, Codex, Cursor's CLI, and many others all read a repo-root `AGENTS.md`, one well-written file covers most of your team regardless of which agent each person uses.
## Patterns that work
Observations from CodeAlive's own production prompt and from how other MCP vendors instruct agents converge on a few rules:
### 1. Imperative plus a trigger condition
State *when* to use the tool, not just that it exists.
```markdown theme={null}
Always use CodeAlive `semantic_search` when exploring how the codebase works,
where something is implemented, or how components relate.
```
A passive mention ("CodeAlive provides semantic search") does not change behaviour; a conditional imperative does.
### 2. Name the built-in tool you are overriding
Agents fall back to their native tools unless the instruction names them explicitly. This is the single most important pattern — and the most commonly missed one:
```markdown theme={null}
Do NOT use the built-in codebase_search or plain grep for exploration questions
before trying CodeAlive `semantic_search` / `grep_search`.
```
Generic phrasing ("prefer CodeAlive for search") loses to the planner's habit; naming the competing tool wins.
### 3. Sequence the tools
Tell the agent what a good exploration looks like as an ordered path, so it doesn't stop at the first tool:
```markdown theme={null}
For codebase questions: `semantic_search` (concepts) or `grep_search` (exact
names) → `fetch_artifacts` on the returned identifiers → answer from the
fetched code, not from snippets.
```
### 4. Teach the query grammar in one line each
The two most common failure modes are keyword-style semantic queries and question-style grep queries. One line each prevents both:
```markdown theme={null}
- `semantic_search`: full English sentences ("Where is retry handling
implemented?"), never bare keywords. Keep identifiers verbatim.
- `grep_search`: the exact literal or regex, never a question.
```
### 5. Keep always-on context small
Instruction files are injected into every request. Keep the CodeAlive section to 10–15 lines; move anything longer into on-demand mechanisms (Cursor's Agent Requested rules, Claude Code skills). A bloated always-on rule gets skimmed by the model and taxes every prompt.
## Universal snippet
This block works verbatim in `AGENTS.md`, `CLAUDE.md`, and `.cline/rules.md`, and as the body of a Cursor `.mdc` rule:
```markdown title="AGENTS.md / CLAUDE.md — CodeAlive section" theme={null}
## CodeAlive context engine
CodeAlive MCP provides semantic search, grep, and code-graph tools over indexed
copies of our repositories (cross-repo, always up to date with the default branch).
- For any codebase exploration — "how does X work", "where is Y implemented",
"what calls Z" — start with CodeAlive `semantic_search`. Do NOT use built-in
file search (grep/glob/codebase_search) for these questions before CodeAlive
has returned nothing useful twice.
- Phrase `semantic_search` as a full English sentence, never bare keywords.
Keep exact identifiers and domain terms verbatim.
- Use CodeAlive `grep_search` for exact symbol names, string literals, error
messages, config keys, and acronyms — pass the literal text, not a question.
- When a result returns an artifact identifier (`repo::path::symbol`), read it
with `fetch_artifacts`; map callers/callees with `get_artifact_relationships`
before claiming how code flows.
- Call `get_data_sources` once per session to discover repository names and pass
them in `data_sources` to scope searches.
- Built-in file tools remain correct for files you are actively editing in the
working tree; CodeAlive covers the indexed history and the repos you don't
have checked out.
```
The last bullet matters: an instruction that bans local tools outright degrades editing tasks. Scope the preference to *exploration of indexed code*, and leave the working tree to the agent's native tools.
## Per-agent specifics
CLAUDE.md routing rules and the search subagent pattern
Rule types, and beating the built-in codebase\_search
AGENTS.md placement and a complete example
Two agent-specific facts worth knowing even before opening those pages:
* **Cursor's built-in `codebase_search` cannot be disabled** in the default Agent mode. The working approach is a precedence rule that names it — see the [Cursor page](/integrations/mcp/cursor#codealive-vs-cursors-built-in-codebase-search).
* **Codex reads the MCP server's own `instructions` field** at initialization, and the CodeAlive server ships tool-choice guidance there. `AGENTS.md` still helps: server instructions describe the tools, while `AGENTS.md` sets project-level precedence over built-ins.
## Verify it works
After adding instructions, test with a question that used to trigger built-in search:
```text theme={null}
"How does authentication work in this project?"
```
Watch the agent's tool calls: the first exploration call should be CodeAlive `semantic_search` (visible in the agent's tool log), not a local grep. If the agent still reaches for built-ins, strengthen pattern #2 — name the specific tool it used and forbid it for exploration questions.
## Related resources
Full example prompt for your own agent on the Tool API
1C:Enterprise specifics — the "metadata" dichotomy
Tool list and connection options
More agent-specific tips