Towards self-improvement

An essential aspect of becoming productive while working with agents is to blend them with code. Your agents need to adapt to the codebase, and your codebase needs to adapt to the agents. For example, you might not necessarily like the commit message that the agent has just produced.

AGENTS.md

One way to steer agents toward doing the right things is to have an AGENTS.md file in the repository root. This file is read by the agent in each thread and defines basic guidance for how it should operate.

You might see different variants of this file across tools — GEMINI.md, COPILOT.md, AGENT.md, CLAUDE.md, and others. In practice, one file is enough: AGENTS.md. It’s supported by nearly all coding agents except Claude Code, which still expects a separate CLAUDE.md.

The simplest solution to keep both files in sync is to create a symlink (symbolic link) from AGENTS.md to CLAUDE.md — see the command below.

Keep this file minimal. Its role is to make sure the agent “does the right thing” every time — not to over‑specify every step.

Example1

# [Project name]

## Rules

- you may be running in parallel with other agents; cooperate to avoid
  conflicts, but avoid committing changes made by others
- add test coverage for new logic and regression fixes where practical
- run `npm lint` to format code and run linters; run `npm test` to run tests
- ignore any backward compatibility - break stuff everywhere if needed

Source: Marek Kaput ’s template.

Example 2

# Sample AGENTS.md file

## Dev environment tips

- Use `pnpm dlx turbo run where «project_name»` to jump to a package
  instead of scanning with `ls`.
- Run `pnpm install --filter «project_name»` to add the package to your
  workspace so Vite, ESLint, and TypeScript can see it.
- Use `pnpm create vite@latest «project_name» -- --template react-ts` to
  spin up a new React + Vite package with TypeScript checks ready.
- Check the name field inside each package's package.json to confirm the
  right name - skip the top-level one.

## Testing instructions

- Find the CI plan in the .github/workflows folder.
- Run `pnpm turbo run test --filter «project_name»` to run every check
  defined for that package.
- From the package root you can just call `pnpm test`. The commit should
  pass all tests before you merge.
- To focus on one step, add the Vitest pattern:
  `pnpm vitest run -t "«test name»"`.
- Fix any test or type errors until the whole suite is green.
- After moving files or changing imports, run
  `pnpm lint --filter «project_name»` to be sure ESLint and TypeScript
  rules still pass.
- Add or update tests for the code you change, even if nobody asked.

## PR instructions

- Title format: [«project_name»] «Title»
- Always run `pnpm lint` and `pnpm test` before committing.

Source: agents.md website.

Claude integration

Create a symbolic link for Claude:

ln -s AGENTS.md CLAUDE.md

This command creates a file CLAUDE.md that points to AGENTS.md. Claude will then read the same rules as all other agents without needing a separate copy.

If possible, commit both files to your repository.

👏 +1

…

More utilities await

AGENTS.md is the simplest place to start, because it gives you immediate leverage without adding much complexity.

As you get comfortable with that baseline, you can introduce more advanced utilities around the agent: skills for reusable workflows, more structured guidance such as Cursor Rules for larger codebases, and MCP integrations for connecting the model to external tools and services.

You do not need all of that on day one. For now, it is enough to understand that these mechanisms exist and become more useful once you already have a stable basic workflow.

When you are ready, continue with Harness engineering, which covers these more advanced building blocks in detail.

👏 +1

…