A Makefile Is the Best Agent Doc: 10 Targets Every Repo Needs Before an Agent Touches It

A Makefile is a valuable tool for any repository, especially when an AI coding agent is interacting with it for the first time. By including specific targets in the Makefile, the agent can interact with the codebase in a controlled and predictable manner, avoiding potential issues that may arise from the agent's guesses.

The Makefile includes ten essential targets that cover various aspects of the development process: help, setup, test, test-one, lint, fmt, typecheck, dev, db-reset, and check. Each target serves a specific purpose, providing a clear and concise way for the agent to navigate the codebase and perform necessary actions.

For instance, the help target lists all available targets, making it easy for the agent to understand the range of options available. The setup target ensures that dependencies are installed exactly as locked in the package manager's lockfile. The test target runs the entire test suite once, while the test-one target allows running tests for a specific file.

The lint and fmt targets ensure code quality by linting and formatting the code, respectively. The typecheck target performs type checking without producing any output files, and the dev target starts a development server.

The db-reset target is particularly important, as it resets the database to a safe state, allowing the agent to work with a known configuration. This target is marked as local only, preventing unintended data loss when the agent is run in a different environment. The check target ensures that all other targets have passed before proceeding, serving as a final gate for the agent.

By including these ten targets in the Makefile, developers can provide the AI coding agent with a well-defined set of actions, reducing the risk of unexpected behavior and ensuring a smooth interaction with the codebase.