Agent Rules

The rules file .claude/rules/microbus.md teaches a coding agent the conventions and idioms of the Microbus framework. It is loaded automatically at the start of every agent session and serves as the agent’s reference manual for how to write correct Microbus code. The file ships with the framework and is one of three layers of agent guidance, alongside skills and CLAUDE.md.

What Rules Cover

Rules are the framework’s “how” knowledge - the patterns and conventions an agent must follow to produce correct Microbus code. The file covers:

  • Project structure. How a Microbus project is laid out, where microservices live, the role of main/, manifest.yaml, the per-microservice API package, and the .claude/ directory.
  • Naming conventions. Microservice hostnames, endpoint method/route conventions, file and package naming.
  • The Connector API. Idiomatic uses of the Connector - how to register endpoints, fire events, define configs and tickers, and access the framework’s plumbing.
  • Error handling. Returning errors from handlers, wrapping with stack traces via errors.Trace, and the framework’s error capture expectations.
  • Logging. Structured logging conventions through svc.LogInfo / svc.LogError, the slog-style key/value attribute style, and what should and should not appear in logs.
  • Authorization patterns. Idiomatic use of requiredClaims expressions for actor-based authorization.
  • Testing patterns. How to write integration tests using the generated Initializer and the testarossa assertion style.
  • Codegen expectations. Which files are agent-edited and which are framework-owned (intermediate.go, generated stubs) and must not be hand-edited.

The rules describe how a microservice is written, not what a particular microservice should do. The “what” comes from the developer’s prompts and the agent’s skills.

Rules vs. Skills vs. CLAUDE.md

Microbus’s agent guidance is layered. Each layer answers a different question:

SourceAnswersUpdated byEdited by hand?
Rules (.claude/rules/microbus.md)How does Microbus code look?Framework releasesNo
Skills (.claude/skills/)How do I do X (add an endpoint, scaffold a CRUD service, upgrade)?Framework releasesNo
Global CLAUDE.md (project root)What does this project care about?DeveloperYes
Local CLAUDE.md (per microservice)Why does this microservice make these design choices?Agent (during work)Yes, but rarely

Rules are universal. They apply to every Microbus microservice in every project. Skills are universal too - canonical playbooks for canonical tasks. CLAUDE.md is where project- and microservice-specific context lives.

Lifecycle

Rules ship with the framework and are version-locked to it:

  • On project bootstrap, the bootstrap skill drops a copy of .claude/rules/microbus.md into the project alongside the rest of the .claude/ setup.
  • On every framework upgrade, the upgrade skill refreshes .claude/rules/microbus.md to match the new release. This is one of the main reasons a bare go get -u is insufficient: it bumps the module but leaves the rules out of sync, so future agent sessions code against stale conventions.

The rules file should therefore be treated as framework-managed. Anything you add by hand will be overwritten on the next upgrade.

Project-Specific Deviations

If a project needs to override or extend the framework conventions - for example, a house style for log keys, a custom error-wrapping pattern, or a project-wide naming choice - the place to record that is the global CLAUDE.md at the project root. The agent reads both the framework rules and the project’s CLAUDE.md at session start, and treats project-level guidance as additive context.

A microservice-specific deviation goes in that microservice’s local CLAUDE.md. The agent maintains the local file as it works, capturing the why behind decisions so that future sessions (or future agents) can safely evolve the code.

See Also

Backward Agentic RAD Agent Skills Forward