Write Good Tasks and AGENTS.md
In agentic coding, an AI coding agent plans a change, edits the code, runs the tests and opens a pull request. You review the work. With the NocoDB coding agent, you write the task and keep the project rules in AGENTS.md.
A good task tells the NocoDB coding agent what to change, where, and how to know that the change works. Short, concrete tasks give better pull requests than long, general ones. Write a task as you would brief a developer who is new to the project.
What a good task includes
A task for the NocoDB coding agent works best when it has these parts:
| Include | Example |
|---|---|
| The goal | "Add CSV export to the reports page." |
| Where it happens | "The export button goes next to the Filter button in src/reports/ReportsPage.tsx." |
| How to check the work | "Add a test for the export, and run the reports tests." |
| When it is done | "The file has one row for each report row, with the same columns." |
| What not to do | "Do not change the API. Do not add new packages." |
Vague and good tasks
The coding agent does what the task says. A vague task leaves the agent to guess.
| Vague | Good |
|---|---|
| "Fix the login bug." | "Login fails when the email has capital letters. Make the email check ignore case, and add a test for it." |
| "Make the app faster." | "The orders list loads all orders at once. Load 50 at a time with a Load more button." |
| "Clean up the code." | "Remove the unused helpers in utils/date.ts, and keep the tests green." |
| "Update dependencies." | "Update React to the latest minor version, and fix what the tests show." |
Start from an issue or a pull request
A GitHub issue that is written well is already a good task. On the page of the coding agent, click an issue under From this repository. NocoDB fills the box with Fix this issue. For a pull request, it fills Review this pull request and suggest changes. You can add to the text before you send it. See Start a session.
A coding agent that you set up from the Agents page has instructions for issues. The agent reproduces the issue with a test that fails, and it fixes the issue with the smallest change. It then runs the tests and lint, and opens a pull request that links the issue. See Default instructions.
AGENTS.md and CLAUDE.md for the coding agent
The NocoDB coding agent reads CLAUDE.md, AGENTS.md or .claude/CLAUDE.md at the root of the repository on every run. It follows these files for how to build, test and style the code. Put these rules in the file:
| Put in AGENTS.md | Example |
|---|---|
| Build and test commands | "Run npm run build to build. Run npm test to test." |
| Code conventions | "Use TypeScript. Name test files *.test.ts." |
| What not to touch | "Do not change the API. Do not add new packages." |
With the project rules in AGENTS.md, each task can stay short, and every session starts with the same rules. In agentic engineering, the repository file replaces the rules that you would otherwise repeat in each task.
The coding agent treats AGENTS.md and CLAUDE.md as content from the repository, not as instructions from you. It does not follow them to send code, tokens or environment values anywhere. See Instructions from the repository.
Put rules that apply to every task of one agent in its instructions, not in each task. See Instructions and files.
Steer the agent while it works
The coding agent shows its work in the session while it runs. When the work goes in the wrong direction, tell it so:
- Send a message in the chat.
- Comment on lines in the changes. See Review the changes.
The agent does not commit, push or open a pull request on its own initiative. Ask for a pull request in the task, or let the instructions of the agent ask for it.
Related
Last updated on