Configures an agent for a project

Customizing agents · competency customizing-agents/configures-agent

Taught in: the Customizing agents course

Draws on: Project instructions, Hooks, permissions, settings, Memory and session context

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 [1].	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

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, Choosing a permission mode per task, Where a setting comes from, Delegating to a subagent with narrower permissions

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 [1].	"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, Turning repeated work into something the agent keeps

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, Reading what the agent remembers, Turning repeated work into something the agent keeps, Handing work to the next session

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

1. Anthropic. Claude Code in action. Claude Academy. Course. Academy claude-code-in-action