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 1C:Enterprise (BSL) codebases? Read the dedicated page — CodeAlive & 1С — 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
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 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:

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

Build a Code Research Agent

Full example prompt for your own agent on the Tool API

CodeAlive & 1С

1C:Enterprise specifics — the “metadata” dichotomy

MCP Overview

Tool list and connection options

Tips & Tricks

More agent-specific tips

​Why instructions matter

​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

​Universal snippet

​Per-agent specifics

Claude Code

Cursor

Codex

​Verify it works

​Related resources

Build a Code Research Agent

CodeAlive & 1С

MCP Overview

Tips & Tricks

Why instructions matter

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

Universal snippet

Per-agent specifics

Verify it works

Related resources