agentleFS
celestiaorgcelestiaorg/celestia-app/AGENTS.md

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.

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
  1. Very specific:

    When editing Go code, always run make build after changes to catch compilation errors immediately.

    line 7
  2. Very specific:

    Before opening PRs that modify Go code, run make lint and make test-short.

    line 28
  3. Very specific:

    All branches use forked cosmos-sdk and celestia-core.

    line 53
  4. Distinctive:

    Follow README.md#contributing for review levels.

    line 78
  5. Distinctive:

    Don't repeat the review tag in the PR description.

    line 79
  6. Distinctive:

    Keep PRs under 700 lines of code.

    line 80

≈ “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.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
AGENTS.md

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 files

Testing

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 detection

Linting

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 issues

Protobuf (requires Docker)

make proto-gen    # Generate protobuf files
make proto-lint   # Lint protobuf files

Architecture

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,multiplexer
  • make 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

  1. Multi-module repo: Copy go.work.example to go.work and run go work sync
  2. 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.
  3. Linking issues: PR descriptions must start with a Closes <link> line when an issue exists, and the link must be clickable. Linear issues use Closes [PROTOCO-1234](https://linear.app/celestia/issue/PROTOCO-1234) — a bare Closes PROTOCO-1234 is not acceptable because GitHub does not linkify it.
  4. 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/, or multiplexer/ 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 an adversarial-reviewer deep 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 /implement skill, 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 /implement directly. 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 gitignored docs/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.

Download now (ZIP)

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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.