From a74ca49a362064e833573c313c24af4d16ab7aec Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=D7=A0=CF=85=CE=B1=CE=B7=20=D7=A0=CF=85=CE=B1=CE=B7=D1=95?= =?UTF-8?q?=CF=83=CE=B7?= Date: Sun, 29 Mar 2026 20:24:23 -0700 Subject: [PATCH] docs: add example conventions to CLAUDE.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Add guidelines for writing examples: self-contained with cleanup, one purpose per file, decode and print results, keep under ~100 lines, platform safety with ContinueOnError(). 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude --- CLAUDE.md | 44 +++++++++++++++++++++++++++++++------------- 1 file changed, 31 insertions(+), 13 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index 30d26fa..afba51f 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -191,23 +191,41 @@ Add the operation to the table in the domain landing page Add the operation to an existing workflow example in `examples/operations/` that covers the same domain. Domain groupings: -| Domain | Example file | -| ------- | ---------------------- | -| Node | `node-info.go` | -| Node | `hostname-update.go` | -| Network | `dns-update.go` | -| Network | `ping.go` | -| Command | `command.go` | -| File | `file-deploy.go` | -| File | `file-changed.go` | -| Agent | `agent-drain.go` | -| Docker | `docker.go` | -| Cron | `cron.go` | -| Health | (used as gate in most) | +| Domain | Example file | +| ------- | -------------------- | +| Node | `node-info.go` | +| Node | `hostname-update.go` | +| Network | `dns-update.go` | +| Network | `ping.go` | +| Command | `command.go` | +| File | `file-deploy.go` | +| File | `file-changed.go` | +| Agent | `agent-drain.go` | +| Docker | `docker.go` | +| Cron | `cron.go` | +| Health | (used as gate) | If no domain match exists, create a new `{domain}.go` file. Every operation must appear in at least one runnable example. +#### Example conventions + +- **Self-contained**: cleanup at the start (separate plan with + `ContinueOnError()`), execute, verify. Must be repeatable. +- **One purpose per file**: demonstrate one domain's operations. + Don't mix in other features (parallel, verbose, broadcast). +- **Cleanup plan pattern**: use a separate `orchestrator.New()` for + cleanup with `ContinueOnError()`, then a main plan for the workflow. +- **Platform safety**: operations that may not work everywhere use + `ContinueOnError()` so the example doesn't crash. +- **Decode and print**: decode at least one result so the example + isn't silent. Use `report.Decode("step-name", &typedStruct)`. +- **Keep it short**: under ~100 lines of code (excluding license). + If longer, you're demonstrating too much — split it. +- **Operation docs link to examples**: every operation doc in + `docs/operations/{domain}/` must link to the example file where + that operation is demonstrated. + ### Step 6: Update README.md Update the operation count and tables in the root `README.md` if the