# Configures an agent for a project

> Competency customizing-agents/configures-agent

Page: https://schubergphilis.github.io/ai-training/competencies/customizing-agents/configures-agent/
License: CC BY-SA 4.0, https://creativecommons.org/licenses/by-sa/4.0/

*Customizing agents* · competency `customizing-agents/configures-agent`

**Taught in:** the [Customizing agents](https://schubergphilis.github.io/ai-training/customizing-agents/) course

**Draws on:** [Project instructions](https://schubergphilis.github.io/ai-training/topics/customizing-agents/instructions/), [Hooks, permissions, settings](https://schubergphilis.github.io/ai-training/topics/customizing-agents/hooks-permissions/), [Memory and session context](https://schubergphilis.github.io/ai-training/topics/customizing-agents/memory/)

## Learning objectives

### Writes instructions that remove a recurring agent mistake (base)

| Claim | Why | Example |
| ----- | --- | ------- |
| Each instruction is traceable to a mistake the agent made in a real session. | Instructions written from imagination pad the file, dilute the ones that matter and are never tested. | After the agent ran `npm install` twice against a pinned lockfile, the learner adds "install with `npm ci`, never `npm install`" and nothing else that day. |
| An instruction says what to do and how the agent can tell it did it, in one or two lines. | Vague guidance such as "write clean code" gives the agent nothing to check itself against. | "Run `mise run ci` before reporting done; it must exit 0" replaces "make sure everything works". |
| The learner removes an instruction when the mistake stops recurring or when a hook or a check now enforces it. | A project file that only grows gets skimmed, and the rules that still matter get lost in it (Claude Code in action, Claude Academy). | Once a pre-commit hook rejects unformatted files, the learner deletes the "always run the formatter" line from the instructions. |

Served by: [Project instructions: AGENTS.md](https://schubergphilis.github.io/ai-training/customizing-agents/instructions/)

### Sets permissions to the least the work needs (base)

| Claim | Why | Example |
| ----- | --- | ------- |
| The learner starts from deny by default and allows the specific commands and paths the task needs. | A broad allowlist granted for convenience is the blast radius of every later mistake. | The settings allow `npm test` and `git diff` without asking, and everything else prompts. |
| The learner separates what the agent may read from what it may write and run. | Reading is nearly always safe, and writing and running are where damage happens. | The agent may read the whole repository but may write only under `src/` and `tests/`. |
| The learner reviews the permission set after a task and removes what was not used. | Permissions accumulate and are never removed on their own. | After the migration is done, the learner removes the database CLI from the allowlist. |

Served by: [Allowing the commands the task needs](https://schubergphilis.github.io/ai-training/customizing-agents/allowlists/), [Choosing a permission mode per task](https://schubergphilis.github.io/ai-training/customizing-agents/permission-modes/), [Where a setting comes from](https://schubergphilis.github.io/ai-training/customizing-agents/settings-layering/), [Delegating to a subagent with narrower permissions](https://schubergphilis.github.io/ai-training/customizing-agents/subagents/)

### Adds a hook that enforces a rule the instructions cannot (base)

| Claim | Why | Example |
| ----- | --- | ------- |
| The learner reaches for a hook when a rule must hold every time, and for an instruction when it is guidance. | An instruction is read and sometimes ignored, but a hook runs whether or not the model remembered (Claude Code in action, Claude Academy). | "Run the formatter before committing" becomes a pre-commit hook after the third unformatted commit. |
| A hook fails loudly and says what to do, and it runs fast enough that nobody disables it. | A silent hook is a mystery to the agent and a slow hook is a hook someone turns off. | The hook prints "lockfile changed but the manifest did not; run `bun install` or revert" and exits non-zero in under a second. |
| The learner tests the hook by making the mistake it is meant to catch. | A hook that has never fired may not work, and the first real mistake is a bad time to find out. | The learner writes a commit with the forbidden pattern and checks that the hook rejects it, before relying on it. |

Served by: [Writing a hook that blocks a mistake](https://schubergphilis.github.io/ai-training/customizing-agents/first-hook/), [Turning repeated work into something the agent keeps](https://schubergphilis.github.io/ai-training/customizing-agents/repeated-work/)

### Decides for each piece of guidance whether to load it or point at it (base)

| Claim | Why | Example |
| ----- | --- | ------- |
| The learner keeps in the instruction file only what nearly every task needs, and replaces the rest with a line that says where it is. | Everything in the file is in context for every task, and a pointer costs one line until a task needs the detail (How Claude remembers your project, Claude Code documentation). | The release procedure moves from the instruction file into a skill, and the file keeps "to cut a release, use the release skill". |
| The learner writes a pointer that says when to follow it as well as where it goes. | A file that an instruction only asks the agent to read is read when the agent decides to open it, so the pointer has to tell it when (How Claude remembers your project, Claude Code documentation). | "Before changing the database schema, read `docs/migrations.md`" instead of "see also `docs/`". |
| The learner knows that an import which pulls a file in at start-up still loads it. | An import makes the file shorter to read and leaves the context just as full (How Claude remembers your project, Claude Code documentation). | The learner moves a 300-line style guide behind a path-scoped rule that loads only for the files it covers, instead of importing it. |

Served by: [Load it, point at it, or cut it](https://schubergphilis.github.io/ai-training/customizing-agents/load-point-prune/)

### Manages what the agent carries between sessions (expert)

| Claim | Why | Example |
| ----- | --- | ------- |
| The learner decides what the agent should carry between sessions and puts it in a file the agent reads, rather than relying on automatic memory. | Automatic memory keeps what the tool thought was important, and a file keeps what the team decided was. | The project's context file records "the staging database is read-only for agents" so no session has to relearn it. |
| The learner reviews what the agent has remembered and deletes what is stale or wrong. | A wrong remembered fact is applied to every future session with full confidence. | The memory file still says the tests take ten minutes. After the test speed-up, the learner removes the line so the agent stops skipping them. |
| When a session's work continues later, the learner has the agent write a handoff: state, decisions, what is left. | Context does not survive the session, and the next session otherwise reconstructs it from the diff, badly. | The session ends with a `HANDOFF.md` that names the failing test and the two approaches already ruled out. |
| The learner turns a fix that sessions had to make more than once into a skill or an instruction. | Repeated work in memory is a symptom, and the cure is a reusable procedure. | After three sessions each worked out how to regenerate the API client, the steps become a skill. |

Served by: [Directing the summary before compaction](https://schubergphilis.github.io/ai-training/customizing-agents/compaction/), [Reading what the agent remembers](https://schubergphilis.github.io/ai-training/customizing-agents/memory-review/), [Notes that go stale](https://schubergphilis.github.io/ai-training/customizing-agents/notes-that-go-stale/), [Turning repeated work into something the agent keeps](https://schubergphilis.github.io/ai-training/customizing-agents/repeated-work/), [Handing work to the next session](https://schubergphilis.github.io/ai-training/customizing-agents/session-handoff/)

### Prunes instruction files line by line (expert)

| Claim | Why | Example |
| ----- | --- | ------- |
| For each line the learner asks whether removing it would cause a mistake, and removes it when it would not. | Rules in a long file get ignored, so every line that does nothing weakens the ones that matter (Best practices for Claude Code, Claude Code documentation). | "Write clean, readable code" goes, because the agent behaves the same without it. |
| The learner removes lines the agent can work out from the code, and lines about problems that have gone away. | Those lines cost context in every session and can go stale while the code changes. | A paragraph describing the folder layout goes, and so does a warning about a build bug that was fixed last year. |
| The learner resolves conflicting lines, including lines in different instruction files that contradict each other. | When two instructions conflict, the agent may follow either one (How Claude remembers your project, Claude Code documentation). | The root file says "use tabs" and a package file says "use spaces", so the learner keeps the package rule and adds the reason for the exception. |
| After a pruning pass the learner watches a few sessions to confirm that nothing broke. | Testing a change to the instructions means watching the agent's behavior, as with any change to a prompt. | The learner runs the usual tasks after the cut and adds back the one line whose removal made the agent skip the formatter. |

Served by: [Load it, point at it, or cut it](https://schubergphilis.github.io/ai-training/customizing-agents/load-point-prune/)

## Alignment

| Framework | Code | Asks | Objectives here |
| --------- | ---- | ---- | --------------- |
| Brilliant Coding with AI | MEM-1, MEM-2 | Manage memory; turn repeated work into reusable knowledge | manages-memory |

## References

- Claude Code in action, Claude Academy, https://academy.claude.com/courses/claude-code-in-action
- How Claude remembers your project, Claude Code documentation, https://code.claude.com/docs/en/memory
- Best practices for Claude Code, Claude Code documentation, https://code.claude.com/docs/en/best-practices