Configuring Your Agent Harness¶

Qin Yu, 21 May 2026, updated 29 May 2026

Agent Configuration¶

A well-configured harness reduces per-session overhead and improves consistency across the team.

Instruction Hierarchy¶

Put information in the right layer:

Rules live in versioned files. Memory is convenience, not governance.

A Lean AGENTS.md Template¶

# Working agreements

## Repository intent
- This repository provides <one-sentence purpose>.
- Prioritise correctness, testability, and reviewer clarity over cleverness.

## Do before editing
- Read the nearest README, architecture notes, and existing tests for the touched area.
- Prefer modifying existing patterns rather than introducing new abstractions.

## Validation
- After code changes, run:
  - `make test`
  - `make lint`
  - `make typecheck`
- If any command fails, fix the issue or explain precisely why it cannot be fixed within scope.

## Boundaries
- Do not add dependencies unless explicitly requested.
- Do not change public APIs without updating docs and tests.
- Do not edit generated files unless the task is explicitly about generation.

## Output contract
- Be concise.
- Summarise touched files, validation run, and unresolved risks.
- Stop after the requested task is complete.

Use AGENTS.md for the essentials, and split some material into skills, scoped instructions, or docs.

References:

• OpenAI Codex AGENTS.md
• GitHub Copilot custom instructions
• Claude Code best practices

Persistent Instructions¶

Persistent instructions are injected on every turn, so keep them short or they become a liability:

• Record project conventions and non-negotiables.
• Add output constraints (e.g. "be concise", "summarise validation results").
• Log recurring agent misses only when the fix generalises.
• Write them yourself; AI-generated instruction files are often verbose and generic.
• Iterate, prune, and rewrite periodically.

Skills¶

Skills are progressive disclosure. They keep global context small while making specialised knowledge available when needed.

A skill is a good fit when a workflow is:

• repeated,
• domain-specific,
• too long for global instructions,
• but too important to re-prompt manually each time.

Example:

---
name: api-change
description: Implement or modify REST API endpoints using our repository conventions. Use this when asked to add or change an endpoint.
allowed-tools: shell
---

When asked to add or modify an API endpoint:

1. Read the nearest route, schema, and service files first.
2. Follow the existing error-handling pattern.
3. Update both request and response schemas.
4. Add or update tests.
5. Run:
   - `pnpm test`
   - `pnpm typecheck`
6. Return:
   - touched files
   - endpoint summary
   - validation results
   - migration or rollout notes if relevant

References:

• GitHub Copilot skills
• OpenAI Codex skills

Custom Agents and Sub-agents¶

Limit each agent's tools, scope, and authority. Do not create vague "expert in everything" agents.

Good sub-agent use cases:

• security reviewer,
• test failure analyst,
• documentation reviewer,
• migration planner,
• codebase researcher,
• dependency auditor.

Example Claude Code-style sub-agent:

---
name: security-reviewer
description: Review diffs and touched files for security flaws, unsafe defaults, auth mistakes, and secret exposure.
model: opus
tools: Read, Grep, Glob, Bash
permissionMode: plan
skills:
  - security-checklist
---

Review only. Do not edit files.

Process:
1. Inspect the current diff and the touched files.
2. Look for authn/authz mistakes, secret handling issues, SSRF, command injection, deserialization risk, and insecure defaults.
3. Report findings by severity.
4. For each finding, include:
   - file
   - exact concern
   - exploit path or failure mode
   - recommended remediation
5. If you find nothing material, say so explicitly and list what you checked.

References:

• GitHub custom agents configuration
• GitHub custom agents for Copilot CLI
• OpenAI Codex subagents
• Claude Code sub-agents

Hooks¶

Instructions are advisory. Hooks are deterministic.

Move "must always happen" behaviour into hooks or CI:

{
  "version": 1,
  "hooks": {
    "postToolUse": [
      {
        "matcher": "edit|write",
        "bash": "./scripts/agent-validate.sh"
      }
    ]
  }
}

Use hooks for:

• linting,
• tests,
• formatting,
• secret scanning,
• dependency policy checks,
• generated-code regeneration.

References:

• GitHub Copilot hooks
• Claude Code best practices

MCP Servers¶

MCP is a standard for exposing tools, resources, and prompts to AI applications. It is useful, but not automatically the cheapest or simplest integration.

Prefer a direct API or native CLI when:

• the integration is narrow,
• the API is stable,
• the call is high-frequency,
• portability does not matter,
• you want minimal token and maintenance overhead.

Prefer MCP when:

• the integration should work across multiple hosts,
• the server exposes tools plus resources plus prompts,
• you want shared internal tooling across Copilot, Codex, Claude, or other clients,
• you want a standard interface for agent-accessible actions.

Remove MCP servers that are not actively useful. Every unnecessary tool increases token overhead and the chance of irrelevant tool calls.

References:

• Model Context Protocol: tools
• Model Context Protocol: resources
• Model Context Protocol: prompts
• GitHub Copilot MCP concepts
• OpenAI Codex MCP