From 777cc23acd33765744615cb1ac99fac46c961dbb Mon Sep 17 00:00:00 2001 From: Thomas Eskenazi Date: Tue, 7 Apr 2026 14:53:32 +0200 Subject: [PATCH] feat: add workflow rules to AGENTS.md for test ordering, template usage, and self-improvement flow --- AGENTS.md | 30 +++++++++++++++++++++++++++--- 1 file changed, 27 insertions(+), 3 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 6a29471f..e9c297d2 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -111,10 +111,16 @@ See [CONTRIBUTING.md](CONTRIBUTING.md) for the full workflow. Key rules: - Open an Issue before starting work - Branch from `main`: `feat/`, `fix/`, or `chore/` prefix - Use [Conventional Commits](https://www.conventionalcommits.org/): `feat:`, `fix:`, `chore:` — no scopes for now +- AGENTS.md improvements are `feat:`, not `chore:` — they add value to the agent workflow - Rebase on `main` before PR — linear history, no merge commits - One logical change per PR — keep it atomic - CI must be green (build, tests, schema validation, Trivy, Gitleaks) +- Always read the repository templates before creating issues or PRs: + - Issues: `.github/ISSUE_TEMPLATE/` — use the matching template and fill in all required fields + - PRs: `.github/PULL_REQUEST_TEMPLATE.md` — follow the structure exactly, do not improvise - Do **not** use `git push --force` — use `--force-with-lease` +- When the user corrects a mistake, note it immediately so the insight is not lost — see [Self-Improvement](#self-improvement) +- When the workflow is complete, review any noted corrections and propose rule updates if warranted ## Bug Workflow (mandatory) @@ -165,16 +171,34 @@ Run the full test suite before committing: mvn test ``` +**Ordering:** +1. Write the tests first — only modify files under `src/test/` (and `src/test/resources/`) +2. Run `mvn test` and confirm the new tests **fail** (proving the bug exists) +3. Only then implement the fix in `src/main/` +4. Run `mvn test` again and confirm all tests **pass** + +Do not edit production code (`src/main/`) and test code (`src/test/`) in the same phase. + All existing tests must stay green. If a pre-existing test fails, investigate before touching it. +When the user corrects a workflow step, note it immediately so the insight is not lost — see [Self-Improvement](#self-improvement). + +### 4. Review noted corrections + +Once the fix is merged (or the PR is open and CI is green), review any corrections the user made during the workflow and evaluate them against the [Self-Improvement](#self-improvement) criteria. Propose rule updates only at this point. + ## Self-Improvement -When a user corrects agent-generated code, evaluate whether the correction should become a new rule in this file. Suggest an AGENTS.md update **only** when all three conditions are met: +When a user corrects agent-generated code or workflow, **note it immediately** so the insight is not lost, then **resume the current workflow** without interruption. Do not propose a rule change mid-workflow — wait until the workflow is complete (see Bug Workflow Step 4, Contribution Workflow end-of-list). + +Suggest an AGENTS.md update **only** when all three conditions are met: -1. The corrected code was **generated by the agent** (not pre-existing code being refactored) -2. The correction is **structural** — it targets a convention, pattern, or style choice (e.g. visibility, naming, test design) — not a one-off logic bug or domain-specific mistake +1. The corrected code or action was **generated by the agent** (not pre-existing code being refactored) +2. The correction is **structural** — it targets a convention, pattern, or style choice (e.g. visibility, naming, test design, workflow step) — not a one-off logic bug or domain-specific mistake 3. The correction is **generalizable** — the same mistake could plausibly recur in a different file or context When all three conditions are met, propose the specific Do/Don't entry and the section it belongs to. Do not apply it — let the user decide. +When the conditions are **not** met, do not propose anything — avoid noise. Most corrections are one-off and do not need a rule. + For reference, the Test Writing Rules and Method Visibility sections in this file were both added through this process.