玉澜andCursor
ad0d2b5012
Route business teams and agents to a flat package helpers layout with
thin {product}.go wiring and {product}_{resource}.go files, and forbid
growing megafiles like chat.go. Keep the harness check local and opt-in.
Co-authored-by: Cursor <cursoragent@cursor.com>
73 lines
3.8 KiB
Markdown
73 lines
3.8 KiB
Markdown
# Product Command Handler Agent Guide
|
|
|
|
This file applies to `internal/helpers/`. Read the root `AGENTS.md`,
|
|
[`CONTRIBUTING.md`](../../CONTRIBUTING.md), and
|
|
[`docs/coding-agent-guide.md`](../../docs/coding-agent-guide.md) first.
|
|
For package/file layout, read
|
|
[`docs/helpers-structure-guide.md`](../../docs/helpers-structure-guide.md)
|
|
before adding or moving product leaves.
|
|
|
|
## Scope and routing
|
|
|
|
`internal/helpers` owns product command construction and handler behavior. Find
|
|
the owning product file and its closest tests before editing.
|
|
|
|
| Concern | Owning surface |
|
|
|---|---|
|
|
| Root/static command wiring or plugin loading | `internal/app` |
|
|
| Product command flags and handler behavior | `internal/helpers` |
|
|
| Helpers file layout / megafile splits | [`docs/helpers-structure-guide.md`](../../docs/helpers-structure-guide.md) |
|
|
| Shared Cobra construction | `internal/cobracmd` |
|
|
| Invocation and transport | `internal/executor`, `internal/transport` |
|
|
| Structured failures and recovery hints | `internal/errors`, `internal/recovery` |
|
|
| Output encoding and projections | `internal/output` |
|
|
| Confirmation and dry-run guards | `internal/safety` and command runtime gates |
|
|
| Agent identity/Schema/parameters | `internal/cli` and [`docs/schema-contributor-guide.md`](../../docs/schema-contributor-guide.md) |
|
|
|
|
Do not modify `internal/app` or shared layers merely to register an ordinary
|
|
product leaf when the existing helper construction already owns it. Cross the
|
|
package boundary only when the task changes that shared contract.
|
|
|
|
## File layout (hard rules)
|
|
|
|
- Stay in flat `package helpers`; do not add `helpers/{product}` subpackages by
|
|
default.
|
|
- Product root `{product}.go` owns `new{Product}Command()` and wires subgroups.
|
|
- Put leaves in `{product}_{resource}.go` by CLI resource (see `sheet_*.go`).
|
|
- Do not grow megafiles such as `chat.go` or `aitable.go`; extract or add the
|
|
resource file instead.
|
|
- Mechanical splits must be behavior-neutral and keep registration symbols
|
|
stable. Details and size guides:
|
|
[`docs/helpers-structure-guide.md`](../../docs/helpers-structure-guide.md).
|
|
|
|
## Command contract
|
|
|
|
- Confirm the current path and flags with `dws <path> --help` and the Cobra
|
|
construction before changing behavior.
|
|
- Keep stdout machine-readable business data. Send progress, warnings, and
|
|
diagnostics through the established stderr/logging paths.
|
|
- Preserve structured error category, stable exit behavior, cause, trace ID,
|
|
and an actionable recovery hint. Do not replace a typed lower-layer failure
|
|
with an unclassified message.
|
|
- Treat paths, JSON payloads, filenames, and remote content as untrusted input;
|
|
use existing validation and sanitization helpers.
|
|
- Mutating or destructive commands must keep their preview/confirmation
|
|
behavior aligned with runtime safety and published Schema metadata.
|
|
- If flags, identity, parameters, selection, or safety metadata change, follow
|
|
the scoped `internal/cli/AGENTS.md` and regenerate from reviewed inputs.
|
|
|
|
## Verification matrix
|
|
|
|
| Change | Required focused evidence |
|
|
|---|---|
|
|
| Handler bug or behavior | package regression test including the failure path |
|
|
| Flags or request mapping | Cobra/help test plus dry-run request assertion when the command supports preview |
|
|
| Output or error behavior | structured payload, stderr/stdout, and exit-code assertions |
|
|
| Mutating behavior | preview/confirmation test; live execution only with explicit authorization and disposable data |
|
|
| Shared helper refactor | affected product tests plus `go test ./internal/helpers/...` |
|
|
| Public command surface | Schema/command gates from `internal/cli/AGENTS.md` |
|
|
|
|
Before handoff, run the narrow package tests, `make format-check`, and the
|
|
admission checks selected by `docs/coding-agent-guide.md`. Do not claim a live
|
|
round-trip when only dry-run or mocked transport was exercised.
|