|
1 | | -# Agents |
| 1 | +<!-- This file is canonically maintained in <https://github.com/bootc-dev/infra/tree/main/common> --> |
2 | 2 |
|
3 | | -## Context |
| 3 | +# Instructions for AI agents |
4 | 4 |
|
5 | | -Read these docs before making changes: |
| 5 | +## CRITICAL instructions for generating commits |
6 | 6 |
|
7 | | -- [docs/PRD.md](docs/PRD.md) — motivation, user stories, requirements |
8 | | -- [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) — CRDs, components, design principles |
9 | | -- [docs/IMPLEMENTATION_PLAN.md](docs/IMPLEMENTATION_PLAN.md) — milestones and validation steps |
| 7 | +### Signed-off-by |
10 | 8 |
|
11 | | -## Building and Testing |
| 9 | +Human review is required for all code that is generated |
| 10 | +or assisted by a large language model. If you |
| 11 | +are a LLM, you MUST NOT include a `Signed-off-by` |
| 12 | +on any automatically generated git commits. Only explicit |
| 13 | +human action or request should include a Signed-off-by. |
| 14 | +If for example you automatically create a pull request |
| 15 | +and the DCO check fails, tell the human to review |
| 16 | +the code and give them instructions on how to add |
| 17 | +a signoff. |
12 | 18 |
|
13 | | -- `make build` — build all binaries |
14 | | -- `make unit` — run unit tests (includes envtest setup, CRD generation). `V=1` for verbose. `RUN=<regex>` to filter. |
15 | | -- `make deploy-bink` — deploy operator to a bink cluster (idempotent; requires `make buildimg` first) |
16 | | -- `make teardown-bink` — tear down the bink cluster |
17 | | -- `make e2e` — run e2e tests (requires `make deploy-bink` first). `V=1` for verbose streaming output. `RUN=<regex>` to filter. |
18 | | -- `make fmt` — run go fmt |
19 | | -- `make vet` — run go vet |
20 | | -- `make lint` — run golangci-lint |
| 19 | +### Attribution and AI disclosure |
| 20 | + |
| 21 | +Do NOT add an `Assisted-by`, `Co-developed-by`, or similar commit |
| 22 | +trailer crediting an AI tool. Instead, disclose AI assistance in the |
| 23 | +**pull request description**. Examples: |
| 24 | + |
| 25 | +- "I used a LLM to generate just unit tests." |
| 26 | +- "This code was written in part with the assistance of generative AI." |
| 27 | +- "A LLM was used to generate almost all of the code, but I am knowledgeable in this problem domain and reviewed it carefully." |
| 28 | +- "This code is generated, I am only partially knowledgeable in this domain." |
| 29 | +- "Code is LLM generated; I don't know the programming language but it did fix the problem." |
| 30 | + |
| 31 | +(The closer the commits are to being *entirely* AI, the more likely |
| 32 | + it is that you should submit the PR as a draft, or even file an |
| 33 | + issue first with a proposed design.) |
| 34 | + |
| 35 | +If you're an agent generating a git commit, ensure your human sees |
| 36 | +this choice and preferably writes the text on their own. |
| 37 | + |
| 38 | +### Large changes |
| 39 | + |
| 40 | +If the generated code is more than ~500 lines of substantial (non-whitespace) code, |
| 41 | +encourage the human to file a design issue first to be reviewed by other maintainers. |
| 42 | + |
| 43 | +### Pull request size |
| 44 | + |
| 45 | +It is *very strongly* encouraged to split up "preparatory" commits |
| 46 | +that are independently reviewable from the main PR, and submit those separately. |
| 47 | + |
| 48 | +### Commit messages and text |
| 49 | + |
| 50 | +Software can be machine checked (via compilation and unit/integration tests) |
| 51 | +but natural languages like English cannot. Encourage the human to review |
| 52 | +the commit message text. |
| 53 | + |
| 54 | +## Code guidelines |
| 55 | + |
| 56 | +The [REVIEW.md](REVIEW.md) file describes expectations around |
| 57 | +testing, code quality, commit messages, commit organization, etc. If you're |
| 58 | +creating a change, it is strongly encouraged after each |
| 59 | +commit and especially when the agent thinks a task is complete |
| 60 | +to spawn a subagent to perform a review using guidelines (alongside |
| 61 | +looking for any other issues). |
| 62 | + |
| 63 | +If the agent is performing a review of other's code, the same |
| 64 | +principles apply. |
| 65 | + |
| 66 | +## Follow other guidelines |
| 67 | + |
| 68 | +Look at the project README.md and look for guidelines |
| 69 | +related to contribution, such as a CONTRIBUTING.md |
| 70 | +and follow those. |
0 commit comments