✨ (go/v4): Add AGENTS.md to the projects

[camilamacedo86]

Closes: #5229

[camilamacedo86]

c/c @vitorfloriano could you please give a hand on the review

[Copilot]

Pull request overview

This PR adds AGENTS.md files to Kubebuilder v4 Go projects to provide AI agents with comprehensive guidance about project structure, critical rules, CLI commands, and best practices. The file is automatically generated during project initialization and includes context-aware documentation that adapts to different CLI tools (e.g., kubebuilder vs operator-sdk).

Key Changes

• Added a new template file agents.go that scaffolds AGENTS.md with comprehensive documentation for AI agents
• Integrated the template into the init scaffolder to generate AGENTS.md at project creation
• Updated all test data directories with generated AGENTS.md files

Reviewed changes

Copilot reviewed 8 out of 8 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
pkg/plugins/golang/v4/scaffolds/internal/templates/agents.go	New template that generates AGENTS.md with project structure, CLI commands, and best practices
pkg/plugins/golang/v4/scaffolds/init.go	Integrated the Agents template into the init scaffolder
testdata/project-v4/AGENTS.md	Generated AGENTS.md for project-v4 test data
testdata/project-v4-with-plugins/AGENTS.md	Generated AGENTS.md for project-v4-with-plugins test data
testdata/project-v4-multigroup/AGENTS.md	Generated AGENTS.md for project-v4-multigroup test data
docs/book/src/multiversion-tutorial/testdata/project/AGENTS.md	Generated AGENTS.md for multiversion tutorial test data
docs/book/src/getting-started/testdata/project/AGENTS.md	Generated AGENTS.md for getting started tutorial test data
docs/book/src/cronjob-tutorial/testdata/project/AGENTS.md	Generated AGENTS.md for cronjob tutorial test data

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[vitorfloriano]

Couldn't we add instructions for building, packaging and deploying the project?

Also, I think it could be useful to add a list with the necessary toolchain for development workflow (kind, kubectl, etc...) just so the agent checks that the user has all the tools needed before trying to work around constraints.

WDYT?

[camilamacedo86]

Hi @vitorfloriano, thanks for the review 🙂

I tried to address your comment in a way that stays generic enough. We need to be careful not to be too opinionated, since users can customize their environments and workflows.

About build / package / deploy instructions: I’m not sure this adds much value for AI commands. Packaging and distribution are often project-specific and usually handled by release pipelines. There are many ways to do it, so it’s hard to define something that works well for most cases.

We should also avoid adding versions or very specific steps, as those can get outdated quickly.

For the toolchain list (kind, kubectl, etc.), it can be useful, but I think we should keep it light. Users may use different tools, and we don’t want to force a single workflow.

Overall, I tried to keep things helpful but flexible.

WDYT?

[vitorfloriano]

@camilamacedo86 Yeah, giving a second thought, I think keeping it generic is best. The addition of AGENTS.md is already a nice change that checks the "AI" box.

Maybe we could add a comment saying that this file was generated but users can customize it. Also, we could link to agents.md where users can learn more about how to write their instructions.

But it is already good as is.

[camilamacedo86]

Hi @vitorfloriano

Thank you for checking it out.

Maybe we could add a comment saying that this file was generated but users can customize it

It is the default behvaiour for all already.
When we do not want the end users touching at all then we say that.
For example, in the PROJECT file.

[camilamacedo86]

Hi @vitorfloriano

I did some changes to try shape and improve it.
Let me know wdyt?
Lets see if we can get this one merged

[camilamacedo86]

/test pull-kubebuilder-e2e-k8s-1-32-0

[camilamacedo86]

/test pull-kubebuilder-e2e-k8s-1-33-0

[vitorfloriano]

I think this version covers the essential. Users can always adjust this file to their specific needs, if necessary.

/lgtm

[k8s-ci-robot]

[APPROVALNOTIFIER] This PR is APPROVED

This pull-request has been approved by: camilamacedo86, vitorfloriano

The full list of commands accepted by this bot can be found here.

The pull request process is described here

Details

Needs approval from an approver in each of these files:

• OWNERS [camilamacedo86]

Approvers can indicate their approval by writing /approve in a comment
Approvers can cancel approval by writing /approve cancel in a comment

[k8s-ci-robot]

@camilamacedo86: The following test failed, say /retest to rerun all failed tests or /retest-required to rerun all mandatory failed tests:

Test name	Commit	Details	Required	Rerun command
pull-kubebuilder-e2e-k8s-1-34-0	c7a03a5	link	unknown	/test pull-kubebuilder-e2e-k8s-1-34-0

Full PR test history. Your PR dashboard. Please help us cut down on flakes by linking to an open issue when you hit one in your PR.

Details

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes-sigs/prow repository. I understand the commands that are listed here.

[camilamacedo86]

/test pull-kubebuilder-e2e-k8s-1-34-0