celestia-app
AGENTS.md421 starsChanged 19 days agoApache-2.0View on GitHub
When editing Go code, always run make build after changes to catch compilation errors immediately. For tests involving timing, concurrency, or networking, check for flakiness with -count=N. Before opening PRs that modify Go code, run make lint and make test-short. celestia-app is a Cosmos SDK-based blockchain implementing Celestia's data availability layer. It runs on celestia-core (a CometBFT fork) via ABCI. All branches use forked cosmos-sdk and celestia-core. The exact versions are pinned in the replace block of each branch's go.mod.
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 repository3 other files it gives its agents.
- .github/copilot-instructions.mdCopilot instructions
- implementSkill
- recoverySkill
The file
We split this AGENTS.md into the rules it gives an agent
6 rules. About 0 are common, 3 are distinctive, and 3 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈3
Distinctive · estimate
This author's own choices. Worth a look.
3
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 7
When editing Go code, always run make build after changes to catch compilation errors immediately.
- Very specific: line 28
Before opening PRs that modify Go code, run make lint and make test-short.
- Very specific: line 53
All branches use forked cosmos-sdk and celestia-core.
- Distinctive: line 78
Follow README.md#contributing for review levels.
- Distinctive: line 79
Don't repeat the review tag in the PR description.
- Distinctive: line 80
Keep PRs under 700 lines of code.
≈ “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
Commands
Building
When editing Go code, always run make build after changes to catch compilation errors immediately.
make build # Build multiplexer version (embeds v3-v10 binaries) into ./build/
make build-standalone # Build v12-only version (no embedded binaries)
make mod # Update all go.mod filesTesting
For tests involving timing, concurrency, or networking, check for flakiness with -count=N.
go test -v -run TestName ./path/to/package # Run a single test
make test-short # Run tests in short mode (1 min timeout)
make test # Run all tests (30 min timeout)
make test-race # Run tests with race detectionLinting
Before opening PRs that modify Go code, run make lint and make test-short.
make lint # Run all linters (golangci-lint, markdownlint, hadolint, yamllint)
make lint-fix # Auto-fix linting issuesProtobuf (requires Docker)
make proto-gen # Generate protobuf files
make proto-lint # Lint protobuf filesArchitecture
celestia-app is a Cosmos SDK-based blockchain implementing Celestia's data availability layer. It runs on celestia-core (a CometBFT fork) via ABCI.
Multiplexer vs Standalone
make build(default): Multiplexer build embeds v3-v10 binaries, enables syncing from genesis through all upgrades. Build tag:ledger,multiplexermake build-standalone: v12-only, lighter. Build tag:ledger
Dependency Forks
All branches use forked cosmos-sdk and celestia-core. The exact versions are pinned in the replace block of each branch's go.mod.
Development Workflow
- Multi-module repo: Copy
go.work.exampletogo.workand rungo work sync - Conventional commits: PR titles must follow conventionalcommits.org and start the subject with exactly one review thoroughness tag:
[low],[medium], or[high](e.g.,docs: [low] clarify setup,fix(api): [medium] handle missing input,fix!: [high] correct gas accounting). Any consensus-breaking change (one that alters deterministic state-machine behavior and requires a coordinated network upgrade) must include a!in the PR title, e.g.fix!: [high] correct gas accounting. Choose the tag using the PR rules below. - Linking issues: PR descriptions must start with a
Closes <link>line when an issue exists, and the link must be clickable. Linear issues useCloses [PROTOCO-1234](https://linear.app/celestia/issue/PROTOCO-1234)— a bareCloses PROTOCO-1234is not acceptable because GitHub does not linkify it. - Hacken bug bounty PRs: When creating a PR that resolves a Hacken bug bounty report, do NOT include details about the bug in the PR description. Instead, link to a Linear issue (as a clickable link, per the previous item) that contains more details on the bug and the link to the Hacken bug bounty report.
AI Safety Invariants
@docs/ai/invariants.md
Every code change must respect the invariants in docs/ai/invariants.md, imported above. If your tool does not expand the import, read that file before changing x/, app/, pkg/, proto/, or multiplexer/. If a task cannot be done without violating one, stop and ask the engineer.
AI Workflow
- Risk tiers: changes touching
x/,app/,pkg/,proto/, ormultiplexer/are risky; docs, test-only changes, scripts, tooling, and.github/are light; risky changes that modify a state transition reachable from ABCI are consensus-critical and also get anadversarial-reviewerdeep review. When in doubt, treat as the higher tier. - Interactive gate: before implementing or reviewing any change, triage the tier. For light changes, state the tier in one line and proceed. For risky and consensus-critical changes, ask the engineer whether to run the invariant workflow (the
/implementskill, or the reviewer agents in.claude/agents/for a review). Give a 2–3 line overview — tier, paths touched, what the workflow would add — and recommend running it. Skip the question when the engineer invoked/implementdirectly. In non-interactive runs, run it. - Declined workflow on a risky change: still state assumptions and get engineer confirmation before writing code; no reviewer agents unless the engineer asks.
- Assumptions notes live in
docs/plans/and are never committed. - Working notes are never committed: implementation plans, review or audit findings, investigation logs, and similar agent working documents (e.g.
docs/<topic>-review.md) go in the gitignoreddocs/plans/or the PR description, not in the diff. Before opening or updating a PR, check the diff for such files and remove them.
Pull Requests
- Follow README.md#contributing for review levels. Use the higher level when unsure and reassess if scope changes.
- Don't repeat the review tag in the PR description; the title already carries it.
- Keep PRs under 700 lines of code; propose independently reviewable splits for larger changes.
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.

