🔄 Recurse.bot

A guide for coding agents to recursively self-improve

Record wins, misses, and collaborator signals so every handoff compounds.

What is Recursive Self-Improvement?

Recursive self-improvement is the process by which coding agents learn from their experiences and continuously enhance their own capabilities. By documenting learnings (both successes and failures), collaborator behaviors, and project-specific knowledge, agents can build upon previous work and become more effective over time.

The AGENTS.md File

The AGENTS.md file serves as a knowledge base that coding agents can read and update. It contains project-specific instructions, conventions, and learnings that help agents work more effectively on the codebase.

🎯 Core Instruction for AGENTS.md

Every coding agent working on a project should update the AGENTS.md file whenever they learn anything important about the project.

Capture both positive and negative learnings, including what to repeat and what to avoid, plus any observed collaborator preferences that can build rapport.

This creates a feedback loop where each agent's discoveries benefit all future agents working on the same codebase, enabling continuous improvement and knowledge accumulation.

What to Document in AGENTS.md

Build & Test Commands: How to lint, build, and test the project
Project Structure: Key directories and their purposes
Coding Conventions: Style guides, naming conventions, patterns used
Common Pitfalls: Known issues and how to avoid them
Dependencies: Important libraries and their versions
Deployment Notes: Environment setup and deployment procedures
Agent-Specific Tips: What works well when making changes
Rapport Cues: Collaborator preferences, communication styles, and formatting asks
Reflection Notes: Periodic suggestions for updating AGENTS.md as the context grows

Sample AGENTS.md Template

Add this to your project's AGENTS.md file to enable recursive self-improvement:

# AGENTS.md - Instructions for Coding Agents

## 🔄 Self-Improvement Directive

**IMPORTANT:** When working on this project, update this file whenever you
learn something important about the codebase. Capture both successes to
repeat and failures to avoid. Include rapport-building observations
about collaborators. This includes:

- New build or test commands that work
- Project conventions you discover
- Common errors and their solutions
- Tips for navigating the codebase
- Dependencies or tools that are essential
- Positive or negative results from experiments
- Collaboration preferences you observe

Your learnings will help future agents work more effectively on this project.

## Project Overview

[Describe the project purpose and main technologies]

## Build & Test Commands

```bash
# Add verified commands here
```

## Coding Conventions

[Document discovered patterns and conventions]

## Known Issues & Solutions

[Document problems encountered and how to solve them]

## Agent Tips

[Tips specifically for agents working on this codebase]

## Rapport & Reflection

- Note collaborator preferences, tone, and formatting asks
- Suggest updates that keep this file concise as the context window grows
- Flag any guidance that should be consolidated or clarified

How Agents Should Use This

Read First: At the start of any task, read the AGENTS.md file to understand project conventions and previous learnings.
Learn Actively: As you work, note any discoveries about the codebase, build process, or effective approaches. Record both wins and missteps.
Update Regularly: Before completing a task, update AGENTS.md with any new knowledge that would help future agents.
Be Specific: Include exact commands, file paths, concrete examples, and collaborator cues rather than vague descriptions.

                Remember: Every piece of knowledge you add to AGENTS.md compounds
                over time. Small contributions add up to a comprehensive guide that makes all
                agents more effective.
            

Benefits of Recursive Self-Improvement

Knowledge Persistence: Learnings survive across sessions and agents
Reduced Redundancy: Agents don't repeat the same discoveries
Faster Onboarding: New agents can quickly understand the project
Higher Quality: Accumulated best practices lead to better code
Error Prevention: Documented pitfalls help avoid repeated mistakes

Getting Started

Create an AGENTS.md file in your project root
Copy the template above as a starting point
Add the self-improvement directive prominently at the top
Begin documenting project-specific information
Encourage all agents to read and update the file

                Pro Tip: The more detailed and accurate your AGENTS.md file,
                the more effective agents will be at working on your project. Invest time in
                maintaining it well.
            