The superpowers of a software engineer

Learn your new powers. That is how I have been thinking about coding with AI. The models are stronger every month, and that can feel like losing control. The shift that helped me was simple. Agents do not replace judgment, they amplify it. They still need clear instruction, guardrails, and context, which are all things we already know how to provide.

Agents need to be instructed. The quickest way to start is to make your repo readable for a coding agent before anything else. A small set of instruction files gives the agent context about architecture, constraints, and skills. It is like onboarding a new teammate who reads a few documents, then starts shipping.

Agent instruction files you can add to a repo

There are a few emerging conventions that many tools already recognize. I have tried the ones below because they are simple to add and create an immediate improvement in code suggestions and refactors.

AGENTS.md

AGENTS.md is a lightweight spec for describing agents, roles, and conventions in plain Markdown. The idea is to tell an agent what hats exist in this codebase, what each role should do, and what tools and constraints apply.

Where it lives: usually at the repository root as AGENTS.md
What it contains: agent roles, capabilities, coding conventions, tools the agent can call, risks to avoid, non goals
When the agent reads it: at session start or the first time the agent indexes the repo, then whenever it needs high level policy or role guidance

# AGENTS

## Role: Backend Engineer
Purpose: Implement secure HTTP APIs and background jobs. Owns data integrity and auth.

Capabilities:
- Design and refactor service modules under `src/`
- Write integration tests in `tests/`
- Review and harden input validation and error handling

Tools:
- Postgres via Prisma CLI
- OpenAPI generator `npm run openapi:gen`
- Test runner `npm test`

Conventions:
- TypeScript strict mode on
- Never return raw errors, map to typed problem responses
- Prefer RBAC checks in service layer

Risks to avoid:
- Leaking secrets to logs
- Deserializing untrusted JSON without schema validation

Non goals:
- Frontend styling changes

SKILL.md

SKILL.md is a single skill definition in Markdown. It documents a repeatable action the agent can perform, with inputs, steps, and expected outputs. Think "how to add an endpoint" or "how to write a migration" written for an agent.

Where it lives: at the repository root as SKILL.md, or one file per skill under a skills/ folder
What it contains: the skill name, when to use it, required context, step by step procedure, acceptance checks
When the agent reads it: when prompted to perform that skill, or when it searches for a procedure to achieve a requested change

# Skill: Add REST endpoint

When to use:
- A new route is needed under `/v1/*` and must be documented in OpenAPI

Inputs:
- Route path, HTTP method, request and response schema

Steps:
1. Define request/response schemas in `src/schemas/*.ts` using zod
2. Implement handler under `src/routes/{resource}.ts`
3. Enforce RBAC in service layer
4. Add OpenAPI spec and run `npm run openapi:gen`
5. Add tests in `tests/{resource}.spec.ts`

Acceptance:
- Tests pass
- OpenAPI docs updated
- Unauthorized access returns 403 with problem+json

CLAUDE.md

CLAUDE.md is read by Claude Code to understand your project context and preferences. It sets expectations about architecture, constraints, and style so the agent can generate code that fits the repo.

Where it lives: at the repository root as CLAUDE.md
What it contains: project overview, architectural map, coding preferences, dependencies, glossary, and explicit non goals
When the agent reads it: when Claude indexes or opens the repo, and whenever it needs guidance about structure or style

# Project overview
Service that exposes a REST API for document processing. Monorepo with `api/` and `worker/`.

# Architecture
- api: Fastify + Prisma, exposes `/v1/*`
- worker: BullMQ processing queue jobs
- db: Postgres 15

# Coding preferences
- TypeScript strict, functional helpers over classes
- Validation with zod at boundaries
- Errors mapped to RFC 7807 problem responses

# Security
- RBAC enforced in service layer
- Never log PII
- All inputs validated with zod

# Non goals
- No GraphQL
- No ORM migrations outside Prisma

Cursor skills

Cursor skills let you define reusable actions the editor can perform on demand. You describe the task and any constraints, then call the skill by name. It is a way to turn repeatable refactors and scaffolds into a button.

Where it lives: commonly under a .cursor/skills/ directory, one file per skill
What it contains: a name, description, when to use it, and the prompt or instructions to carry out the action, sometimes with file globs or parameters
When the agent reads it: when you invoke the skill explicitly, or when Cursor suggests a relevant skill for the current change

# .cursor/skills/add-zod-validation.yaml
name: add-zod-validation
description: Add zod schemas for incoming HTTP handlers and enforce parsing at boundaries
when_to_use: New or existing route lacks input validation
prompt: |
  For each handler in the selected files:
  - Create a zod schema for request params, query, and body
  - Parse inputs at the start of the handler
  - Propagate typed results to the service layer
acceptance:
  - Handlers fail fast with 400 on invalid input
  - Types inferred from zod flow through to callers

Reducing tokens without losing context

Strong agents are context hungry. The more repo context they can carry, the better the plans and code. Token limits still exist, so it helps to shrink what you send without removing meaning. Two open source tools to consider are below. Treat their headline numbers as directional. Real savings vary by codebase and prompt shape.

Ponytail

Ponytail compresses source context by removing redundancy and boilerplate before it reaches the model. It aims to keep identifiers, structure, and semantics while dropping noise that the model can restore.

Claimed reduction: The project page claims up to 70 percent fewer tokens
How it helps: better fits large repos into a context window, faster iteration on whole module refactors, cheaper runs when doing multi file edits

Link to the project is in the references. I found it easiest to start by running it on a subfolder and diffing the compressed output, then deciding which parts to feed to the agent.

Caveman

Caveman focuses on aggressive code compaction and deduplication, with options to strip comments and normalize structures. It tries to maximize semantic density while keeping code understandable by models.

Claimed reduction: The site claims up to 90 percent fewer tokens
How it helps: lets an agent hold more of a repository in working memory, which improves cross file reasoning and reduces back and forth retrieval

I would sanity check any compaction pass by round tripping a few functions through the agent. If it restores them cleanly and the tests pass, you can be bolder with scope.

A practical path forward

The pattern here is not flashy. Put clear intent into the repo, then give the agent the smallest useful context that still preserves meaning. Start with one instruction file at the root. Add a single skill that matches a task you repeat every week. Try a token reduction pass on a small slice of the code. Each step is easy, and each one makes the agent feel more like a teammate you trust.