Instructing Coding Agents

Why instructions matter

Connecting the CodeAlive MCP server 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 BSL codebases? Read the dedicated page — CodeAlive for BSL — first: the word “metadata” has a language-specific meaning, and agent instructions need to account for it.

Know what the instruction controls

Reliable code retrieval has two separate parts: CodeAlive keeps a server-side index of the default branch, while the coding agent must retrieve the right evidence for the task at hand. An instruction file improves the second part. It cannot compensate for a repository that is missing, still processing, or unavailable to the current connection. Start a research task with get_data_sources, passing the task as its query. This confirms the available source boundary and indexing status while narrowing multi-repository work to the most relevant sources. If an expected repository is absent or not ready, the agent should say so instead of searching an unrelated checkout and presenting the result as complete.

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
Codex (CLI / App / IDE)	`AGENTS.md` (repo root) + `~/.codex/AGENTS.md` (global)	See Codex setup
Cursor	`.cursor/rules/*.mdc`	Legacy `.cursorrules` is deprecated. See Cursor setup
Cline	`.cline/rules.md`	See Cline setup
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.

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:

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:

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:

- `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 always-on CodeAlive section compact; move detailed examples and troubleshooting 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.

6. Define the local–indexed boundary

The server-side index and the local working tree answer different questions. Use CodeAlive for architecture, cross-repository discovery, default-branch code, and repositories that are not checked out. Use local file tools for uncommitted changes and files the agent is actively editing. Say this explicitly. Otherwise agents tend to overcorrect in one direction: they either ignore CodeAlive and search only the checkout, or use indexed results to make claims about changes that exist only in the working tree.

7. Bound the work and require evidence

Efficient retrieval is a short, scoped path rather than a loop of broad searches:

Call `get_data_sources` once with the current task as `query`. Search only the
relevant sources, reuse returned artifact identifiers, and fetch the code needed
to support the answer. If a source or identifier is unavailable, report the
boundary instead of guessing.

This reduces noisy results and unnecessary requests while making failures visible. It also gives you something concrete to evaluate: which sources the agent selected, which artifacts it read, and whether its answer is grounded in those artifacts.

Universal snippet

This block works verbatim in AGENTS.md, CLAUDE.md, and .cline/rules.md, and as the body of a Cursor .mdc rule:

AGENTS.md / CLAUDE.md — CodeAlive section

## 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 with the current task as `query`; use the returned
  names in `data_sources` to scope searches. If an expected source is missing or
  not ready, report that boundary instead of guessing.
- 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 Code

CLAUDE.md routing rules and the search subagent pattern

Cursor

Rule types, and beating the built-in codebase_search

Codex

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.
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:

"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. Do not stop at one successful demo. Keep a small set of representative questions — architecture, exact-symbol lookup, cross-repository flow, and a working-tree change — and rerun them when you change the model, agent, or instruction. Check the tool trace for four quality signals:

the agent selected CodeAlive before built-in search for indexed-code exploration;
get_data_sources selected the intended repository or workspace;
the answer was based on fetched code rather than search snippets alone;
local tools were used when the claim depended on uncommitted changes.

This lightweight evaluation set turns instruction quality into a repeatable gate instead of a subjective impression. It also exposes wasted calls: repeated broad searches, unscoped multi-repository queries, or expensive synthesis before direct retrieval.

Build a Code Research Agent

Full example prompt for your own agent on the Tool API

CodeAlive for BSL

BSL specifics — the “metadata” dichotomy

MCP Overview

Tool list and connection options

Tips & Tricks

More agent-specific tips

Getting Started

Features

Model Context Protocol

Agent Skills & Plugins

Instructing Agents

Instructing Coding Agents

Why instructions matter

Know what the instruction controls

Where instructions live

Patterns that work

1. Imperative plus a trigger condition

2. Name the built-in tool you are overriding

3. Sequence the tools

4. Teach the query grammar in one line each

5. Keep always-on context small

6. Define the local–indexed boundary

7. Bound the work and require evidence

Universal snippet

Per-agent specifics

Claude Code

Cursor

Codex

Verify it works

Build a Code Research Agent

CodeAlive for BSL

MCP Overview

Tips & Tricks

​Why instructions matter

​Know what the instruction controls

​Where instructions live

​Patterns that work

​1. Imperative plus a trigger condition

​2. Name the built-in tool you are overriding

​3. Sequence the tools

​4. Teach the query grammar in one line each

​5. Keep always-on context small

​6. Define the local–indexed boundary

​7. Bound the work and require evidence

​Universal snippet

​Per-agent specifics

Claude Code

Cursor

Codex

​Verify it works

​Related resources

Build a Code Research Agent

CodeAlive for BSL

MCP Overview

Tips & Tricks

Why instructions matter

Know what the instruction controls

Where instructions live

Patterns that work

1. Imperative plus a trigger condition

2. Name the built-in tool you are overriding

3. Sequence the tools

4. Teach the query grammar in one line each

5. Keep always-on context small

6. Define the local–indexed boundary

7. Bound the work and require evidence

Universal snippet

Per-agent specifics

Verify it works

Related resources