# Pointing agents at the folder

No agent loads `martech-context/` just because it exists. Add a short pointer to the project instruction file each client reads, then prove the agent used it. Checked against vendor docs on 2026-10-17; confirm live before quoting limits.

## Principle: point, do not paste

- The pointer names `martech-context/README.md` and says to read only the files a task needs. The index stays small; detail is retrieved on demand.
- Do not paste or import the whole folder into an always-loaded instruction file. It wastes context on every task, and long instruction files are followed less consistently.
- Keep one canonical copy. If a client needs its own file format, that file points to the folder; it does not duplicate definitions.
- Instruction files are context, not enforcement. Claude Code's memory docs say so explicitly and point to hooks for blocking actions. "Never write to the CRM" in a pointer is guidance; the block belongs in the client's permission settings, hooks or the MCP server's read-only mode.

Snippets to adapt: `assets/agent-pointer-snippets.md`.

## AGENTS.md

- An open format: a Markdown file at the repository root, with optional nested files; the nearest file to the edited path takes precedence. The agents.md site lists Codex, Cursor, GitHub Copilot's coding agent and others as supporting it.
- Codex: reads `AGENTS.md` (or `AGENTS.override.md`) from the Codex home and from each directory between the project root and the working directory, concatenated root first. The combined size is capped by `project_doc_max_bytes`, 32 KiB by default. One more reason to point rather than paste.
- Cursor: reads `AGENTS.md` at the root and in subdirectories, with more specific files taking precedence.
- GitHub Copilot: `AGENTS.md` files anywhere in the repository, nearest takes precedence; `.github/copilot-instructions.md` for repository-wide instructions; `.github/instructions/NAME.instructions.md` with an `applyTo` glob for path-specific instructions.

## CLAUDE.md

- Project instructions live in `./CLAUDE.md` or `./.claude/CLAUDE.md`. If there is no `CLAUDE.md` or `CLAUDE.local.md` in the working directory or above, Claude Code reads `AGENTS.md` instead (v2.1.277 or later, per the docs checked on 2026-10-17); if both exist, by default it reads only the `CLAUDE.md` files. A `CLAUDE.md` that imports `AGENTS.md` loads both, which is the safe choice for a repository shared across agents.
- `@path/to/file` imports expand into context at launch. Relative paths resolve from the file that contains the import, and imports can nest four hops deep. A path inside backticks is not imported, so write `` `martech-context/metrics.md` `` to mention a file without loading it.
- Import only the index (`@martech-context/README.md`) if anything. Importing every context file loads all of it into every session.
- Anthropic's guidance is to keep each `CLAUDE.md` under about 200 lines.

## Cursor rules

- Project rules live in `.cursor/rules/` as `.mdc` files; a plain `.md` file there is ignored by the rules system.
- Front matter fields: `description`, `globs`, `alwaysApply`. A rule with a description can be applied when relevant, which suits a pointer to the folder.
- `@file` mentions in a rule tell the agent where to look; the file is read when needed, not inlined.

## Prove the agent read it

A pointer that is never followed is common. After adding it:

1. Start a fresh session in the repository.
2. Ask one known-answer question from the context test set, for example "What is our CAC definition and which denominator does it use?"
3. Pass: the answer names the metric ID and version from `metrics.md` and cites the file. Fail: a generic definition, or a definition without the file reference.
4. Ask one question the folder says to refuse or escalate (a write action, or a metric marked draft). Pass: the agent stops or labels it unapproved.
5. Record the result and date in `decisions.md` under the release log, so later failures can be compared.

## Other clients

Chat clients without repository access (web chat apps, custom assistants) need the content supplied differently: a project knowledge upload, a connector, or a vendor context store. Treat each as a derived copy, listed in `stack.md` with the version it holds, and refresh it after every change to the canonical files.