Skip to content

docs(agents): clarify subpackage layout for flat groups #857

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
natalie-o-perret merged 1 commit into from
Jul 2, 2026
Merged

docs(agents): clarify subpackage layout for flat groups #857

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
26 changes: 19 additions & 7 deletions AGENTS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,6 +9,8 @@ exist in `cmd/storage/`, `cmd/dns/`, `cmd/dbaas/` and are legacy.
Read this file before writing any new command:
`cmd/aiservices/deployment/deployment_create.go`

For subcommand placement in an existing group, also read `## Folder layout` below.

Skeleton:

```go
Expand Down Expand Up @@ -65,6 +67,15 @@ Global alias vars to use for `CmdAliases()`:

## Folder layout

**Anti-pattern: don't extend flat layouts.** `cmd/storage/`, `cmd/dns/`,
`cmd/dbaas/` and similar are legacy flat groups. Adding or refactoring a
subcommand under one of them MUST promote the cluster to its own subpackage
following the layout already used elsewhere in the repo —
`cmd/aiservices/deployment/` is the canonical example (`deployment.go`
declares `var Cmd`; siblings live as `deployment_<verb>.go` in the same dir).
Concrete case in flight: `cmd/storage/storage_bucket_lifecycle*.go` ->
`cmd/storage/bucket/lifecycle/{lifecycle,lifecycle_show,lifecycle_set,lifecycle_delete}.go`.

New command group:

```
Expand All @@ -89,19 +100,20 @@ setup. See `cmd/aiservices/deployment/deployment_create_test.go`.
## File header on every AI-touched file

Add a comment at the top of every file you create or modify. Use the
appropriate syntax for the language, and pick the right verb:
appropriate syntax for the language, and pick the right verb. Substitute
`<model>` with your own identifier (e.g. `claude-sonnet-4.6`, `gpt-5`, etc.):

```go
// AI-generated by claude-sonnet-4.6 - not reviewed yet // new file
// AI-modified by claude-sonnet-4.6 - not reviewed yet // existing file
// AI-generated by <model> - not reviewed yet // new file
// AI-modified by <model> - not reviewed yet // existing file
```
```yaml
# AI-generated by claude-sonnet-4.6 - not reviewed yet
# AI-modified by claude-sonnet-4.6 - not reviewed yet
# AI-generated by <model> - not reviewed yet
# AI-modified by <model> - not reviewed yet
```
```html
<!-- AI-generated by claude-sonnet-4.6 - not reviewed yet -->
<!-- AI-modified by claude-sonnet-4.6 - not reviewed yet -->
<!-- AI-generated by <model> - not reviewed yet -->
<!-- AI-modified by <model> - not reviewed yet -->
```

The reviewer removes the line once they have read and approved the file.
Expand Down