axum-harness
AGENTS.md48 starsChanged 6 months agoApache-2.0View on GitHub
Thin coordination protocol for this repository. Keep this file stable, short, and cross-cutting. Put volatile plans in docs/_local/. Communication MUST be Chinese. Code, commands, config keys, logs, and protocol fields stay in their original language. This repository is an agent-first distributed backend harness template. Default backend anchor: counter-service. Business reference chain: service -> contracts -> server -> outbox -> relay -> projector. Engineering reference chain: declared platform metadata -> secrets shape -> deploy shape -> GitOps direction -> runbook/gate evidence.
- Reads credentials
Where files are headingNew AGENTS.md files have more rules about keeping secrets out of the code, and fewer about code style.
Of the AGENTS.md files we read, the 32,671 first seen in the last six months, against the older ones: the kind of rule that gained most share, and the kind that lost most. About files like this in general, not this one, and an estimate, since a kind is a pattern in the words.
In this repository13 other files it gives its agents.
- backend-engineeringSkill
- contract-agentSkill
- harness-architecture-reviewSkill
- harness-diagnoseSkill
- harness-grillSkill
- harness-tddSkill
- harness-zoom-outSkill
- plannerSkill
- platform-ops-agentSkill
- server-agentSkill
- service-agentSkill
- skill-authoringSkill
- worker-agentSkill
The file
Show its rules and text
We split this AGENTS.md into the rules it gives an agent
24 rules. About 0 are common, 15 are distinctive, and 9 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈15
Distinctive · estimate
This author's own choices. Worth a look.
9
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- could be automatic: a setting could enforce it
- Very specific: line 17
Default backend anchor: counter-service.
- Distinctive: line 40
Prefer simple, explicit, typed, testable code.
- Distinctive: line 41
Do not add speculative features, abstractions, compatibility layers, or configurability.
- Distinctive: line 44
Do not hand-edit generated artifacts.
- Distinctive: line 53
Prefer executable specification: tests, schemas, validators, gates, examples.
- Distinctive: line 54
Do not create planning docs unless the user explicitly asks for a durable document.
- Very specific: line 57
If a written note is needed during implementation, keep it in docs/_local/ or the PR/handoff, not tracked docs.
- Distinctive: line 64
When determining current state, trust evidence in this order:
- Distinctive: line 76
Never infer file/module existence solely from target-state documentation.
- Very specific: line 77
Use evidence labels consistently: declared, checked, tested, proven.
- Very specific: line 85
Prefer editing existing code, tests, schemas, validators, gates, or agent/.
- Very specific: line 86
Prefer PR notes, handoff text, issue comments, or docs/_local/ for temporary reasoning.
- Distinctive: line 87
Do not create tracked docs to record ordinary implementation progress.
- Very specific: line 88
Do not create vocabulary, status, audit, checklist, or planning docs in tracked docs/.
- Distinctive: line 89
Do not create new docs categories.
- Very specific: line 90
Do not promote _local material into tracked docs without explicit user approval.
- Distinctive: line 98
When should it be reviewed or deleted?
- Distinctive: line 167
Default backend-core development should prefer path-scoped guardrails and:
- Very specific: line 171
Use just verify for broader repo-wide backend-core confidence.
- Distinctive: line 173
Do not treat passing gates as the goal.
- Very specific: line 185
No opaque bash -c migrations into Rust.
- Distinctive: line 187
Write operations must distinguish dry-run from apply.
- Distinctive: line 200
Add or update regression verification at the same semantic level.
- Distinctive: line 206
When reporting completion, state:
≈ “Common” is an estimate: at least 1 in 5 of the 41,581 AGENTS.md files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
AGENTS.md
Thin coordination protocol for this repository. Keep this file stable, short, and cross-cutting. Put volatile plans in
docs/_local/.
1. Language
Communication MUST be Chinese.
Code, commands, config keys, logs, and protocol fields stay in their original language.
2. Repository Identity
This repository is an agent-first distributed backend harness template.
Default backend anchor: counter-service.
Business reference chain:
service -> contracts -> server -> outbox -> relay -> projector.
Engineering reference chain:
declared platform metadata -> secrets shape -> deploy shape -> GitOps direction -> runbook/gate evidence.
Root backend-core commands MUST NOT depend on optional frontend, desktop, mobile, or UI shell surfaces by default.
Backend deployable secrets use SOPS + age as the canonical shape. Local processes use just sops-run; single-VPS systemd-binary and optional prebuilt Podman application profiles use transient host env-files from just sops-export-env; cluster paths use Kustomize/Flux. Do not make .env the backend reference path.
Runtime hosts do not compile first-party Rust code. Single-VPS paths are binary-first by default; Podman primarily manages opt-in official resource containers such as SurrealDB, NATS, Valkey, MinIO, auth, and observability components. Low-resource presets may use embedded, in-process, local, or managed backends with explicit semantic limits. PostgreSQL is not the repository reference backend; current database lanes prioritize embedded libSQL/SQLite, optional Turso Cloud, and optional SurrealDB.
3. Operating Posture
Act as a senior distributed-systems engineer in a long-lived codebase.
Default rules:
- Read before changing.
- Understand the invariant before touching code.
- Fix the smallest causal closed loop, not the nearest symptom.
- Prefer simple, explicit, typed, testable code.
- Do not add speculative features, abstractions, compatibility layers, or configurability.
- Touch only lines required by the task.
- Match existing style.
- Do not hand-edit generated artifacts.
- Surface uncertainty instead of guessing.
- Verification not executed must not be reported as passed.
4. Development Loop
For SDD/BDD/TDD-style work:
- Translate the request into the smallest verifiable behavior.
- Prefer executable specification: tests, schemas, validators, gates, examples.
- Do not create planning docs unless the user explicitly asks for a durable document.
- For bugs, reproduce or localize first; then repair the smallest causal boundary.
- A spec is not done until it is represented by code, tests, contracts, validators, or gates.
- If a written note is needed during implementation, keep it in
docs/_local/**or the PR/handoff, not tracked docs. - Describe observable behavior before internal structure.
- Name the boundary and invariant before adding features.
- Docs and YAML are not proof.
5. Truth Hierarchy
When determining current state, trust evidence in this order:
- code, schemas, validators, tests, gates, scripts, and command output
- generated artifacts only when produced from current sources and checked for drift
platform/model/**andservices/*/model.yamlas declared metadata indexesagent/**manifests and.agents/**skills- prose documentation
Rules:
- Executable evidence beats docs and YAML.
- Metadata can declare intent; it does not prove behavior.
- Never infer file/module existence solely from target-state documentation.
- Use evidence labels consistently:
declared,checked,tested,proven.
6. Documentation Write Control
Agents MUST NOT create new tracked files or directories under docs/** without explicit user approval for the exact path and purpose.
Default behavior:
- Prefer editing existing code, tests, schemas, validators, gates, or
agent/**. - Prefer PR notes, handoff text, issue comments, or
docs/_local/**for temporary reasoning. - Do not create tracked docs to record ordinary implementation progress.
- Do not create vocabulary, status, audit, checklist, or planning docs in tracked
docs/**. - Do not create new docs categories.
- Do not promote
_localmaterial into tracked docs without explicit user approval.
A tracked doc proposal must answer:
- What invariant or long-lived decision does this preserve?
- Why is an existing file insufficient?
- What executable source does it point to?
- Who owns it?
- When should it be reviewed or deleted?
7. Reading Paths
Backend tasks read:
AGENTS.mdagent/codemap.ymlagent/manifests/routing-rules.ymlagent/manifests/gate-matrix.yml- relevant
docs/architecture/**only when architecture doctrine is directly needed - relevant
docs/adr/**only when a durable decision is directly involved
Structure, naming, ownership-boundary, gate/evidence, or control-plane tasks also read:
agent/architecture/repository-ontology.ymlagent/architecture/directory-grammar.ymlagent/architecture/naming-conventions.ymlagent/architecture/gate-taxonomy.ymlagent/architecture/evidence-taxonomy.ymlagent/architecture/entropy-guardrails.yml
Rename, move, split, merge, delete, archive, boundary migration, adapter relocation, workspace reshaping, or recipe reclassification tasks also read:
agent/task-profiles/refactor.yml
Tooling, scripts, gates, or repo-control tasks also read:
Justfilejustfiles/README.mdjustfiles/**moon.ymltools/repo-tools/**
Infra, secrets, topology, or deploy tasks also read:
docs/operations/**platform/model/**- relevant
infra/**andops/**
Bug reports and regressions start from executable evidence: failing command, test, validator, schema, log, or reproduction path.
8. Routing
Full routing lives in agent/manifests/routing-rules.yml.
Quick reference:
| Path | Primary owner |
platform/model/**, platform/schema/**, infra/**, ops/** | platform-ops-agent |
packages/contracts/**, docs/contracts/** | contract-agent |
services/** | service-agent |
servers/** | server-agent |
workers/** | worker-agent |
tools/repo-tools/**, Justfile, justfiles/**, moon.yml | planner |
AGENTS.md, agent/**, .agents/**, root config | planner |
docs/architecture/**, docs/adr/**, docs/governance/** | planner |
Multi-domain dispatch order: platform-ops -> contract -> service -> server/worker -> verification.
9. Gate Selection
Gate selection is based on changed paths, risk category, and evidence level.
Use agent/manifests/gate-matrix.yml.
Default backend-core development should prefer path-scoped guardrails and:
just check-backend-primary
Use just verify for broader repo-wide backend-core confidence.
Do not treat passing gates as the goal. Gates are evidence for restored behavior.
10. Tooling Control Plane
just is the human command surface. Keep recipes thin.
moon is task orchestration. Keep task graph and cache inputs there.
tools/repo-tools is the Rust repo-control CLI for reusable validation, generation, drift, routing, and operational logic.
Rules:
- No opaque
bash -cmigrations into Rust. - External commands need structured args, explicit cwd, preflight checks, and clear errors.
- Write operations must distinguish dry-run from apply.
- Secret-handling commands must redact values.
- Generated directories are read-only.
- High-risk operations require plan, preflight, execute, and verify phases.
11. Bug Fix Protocol
For bugs, failing gates, regressions, and suspicious behavior:
- Reproduce or localize with executable evidence when feasible.
- Identify the violated invariant.
- Determine the causal boundary.
- Make the minimal complete repair at that boundary.
- Add or update regression verification at the same semantic level.
- Run relevant gates.
- State residual risk if the fix is tactical.
12. Completion Report
When reporting completion, state:
- what changed
- why it restores or improves the relevant invariant
- what verification ran
- what was not run
- residual risk or uncertainty
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

