agentleFS
Sign inStart free
cosmoscosmos/cosmos-sdk/AGENTS.md

cosmos-sdk

AGENTS.md7.1k starsChanged 8 months agoApache-2.0View on GitHub

This file provides guidance for automated agents contributing to this repository. Each of the following directories has its own go.mod and must be tidied / tested independently: Running go test ./... from the repo root only tests the root module. Use make test so the run-tests target walks every submodule.

Trending

Quiet this year.about the whole repository

Dec 2025: 0 mentionsJan 2026: 0 mentionsFeb 2026: 0 mentionsMar 2026: 0 mentionsApr 2026: 0 mentionsMay 2026: 0 mentionsJun 2026: 0 mentionsJul 2026: 0 mentionsAug 2026: 0 mentionsSep 2026: 0 mentionsOct 2026: 0 mentionsNov 2026: 0 mentions
Dec 2025Jun 2026Nov 2026
Mentions a month of the cosmos/cosmos-sdk repository that our weekly crawl found. There is no adoption data for this file yet.

Who's talking about cosmos/cosmos-sdk

The biggest 5 of 62 mentions linking to the repository that our crawl found. Each line is their own headline.

See all 62

Talked about on GitHub, Stack Overflow, Hacker News and Bluesky (62 times).

On GitHub · 48

43 more on GitHub

On Stack Overflow · 10

5 more on Stack Overflow
  • 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 31,439 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.

The file

We split this AGENTS.md into the rules it gives an agent

6 rules. About 0 are common, 0 are distinctive, and 6 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈0

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 6

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

    Protobuf changes: Run make proto-all (format, lint, generate).

    line 61
  2. Very specific:

    Mocks: If you add or change interfaces that require mocks, run make mocks before pushing.

    line 62
  3. Very specific:

    Lint fixes: Run make lint-fix to auto-fix lint issues.

    line 63
  4. Very specific:

    Enterprise tests: When changing enterprise modules, also run make enterprise-all-test (or make enterprise-poa-test / make …

    line 64
  5. Very specific:

    Add entries to CHANGELOG.md under the ## UNRELEASED section.

    line 70
  6. Very specific:

    Follow the Conventional Commits specification.

    line 80

≈ “Common” is an estimate: at least 1 in 5 of the 40,246 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

Repository guidelines for coding agents

This file provides guidance for automated agents contributing to this repository.

Repository Overview

  • This is the Cosmos SDK, a modular blockchain SDK for building application-specific blockchains.
  • The project is written in Go. Key areas:
    • x/ — Core SDK modules (auth, bank, staking, gov, distribution, consensus, etc.) and supplementary modules (authz, feegrant, epochs, etc.)
    • baseapp/ — Base application and ABCI handling
    • client/ — CLI and client utilities
    • store/ — State storage (IAVL, multistore)
    • crypto/ — Key types and signing
    • simapp/ — Demo application (simd) used for testing and as a reference
    • contrib/x/ — Deprecated modules (circuit, crisis, nft); not actively maintained and not covered by the Bug Bounty program
    • enterprise/ — Enterprise modules (poa, group) with different licensing; see enterprise/README.md. (x/group moved here from contrib/ in v0.54.0.)
  • Most unit tests live next to the code they test. The tests/ directory holds cross-cutting tests: tests/integration/ (integration), tests/e2e/ (e2e), tests/systemtests/ (system), tests/fuzz/ (fuzz).
  • Protobuf definitions live under proto/.
  • Agents should not run test-e2e, test-sim-*, or test-system by default — they are slow, often need Docker or pre-built binaries, and depend on environment specifics. Run them only when a change explicitly requires that level of coverage.

Submodules

Each of the following directories has its own go.mod and must be tidied / tested independently:

  • Library submodules: api, client/v2, collections, core, depinject, errors, log, math, store
  • App / test / tools: simapp, tests, tests/systemtests, tools/cosmovisor (built via make cosmovisor), tools/confix (built via make confix), tools/systemtests
  • Enterprise: enterprise/poa, enterprise/poa/simapp, enterprise/group, enterprise/group/simapp

Running go test ./... from the repo root only tests the root module. Use make test so the run-tests target walks every submodule.

Documentation

  • API & tutorials: https://docs.cosmos.network/
  • Architecture: docs/architecture/ — follow existing patterns when adding features
  • Module overview: x/README.md — lists all modules and their purposes
  • Upgrade notes: UPGRADING.md — required reading before introducing a breaking change; add a corresponding entry alongside the changelog note
  • Security: SECURITY.md — report security-sensitive findings here, not in a normal PR

Scope

  • IBC is maintained in a separate repo (ibc-go); do not add IBC logic to the Cosmos SDK.
  • Deprecated modules in contrib/x/ (circuit, crisis, nft) — avoid adding new features; prefer core x/ modules.

Agent guardrails

  • State-machine and consensus code requires extra care. Changes that affect deterministic state must use the State Machine Breaking changelog stanza and usually warrant an UPGRADING.md entry.
  • Do not hand-edit generated files. *.pb.go, *.pb.gw.go, mocks under testutil/, and similar generated output should be regenerated via make proto-all / make mocks.
  • Do not edit go.sum, go.work, or go.work.sum manually — use make tidy-all to update dependencies across all modules.
  • Do not run golangci-lint directly with custom paths — use make lint, which invokes ./scripts/go-lint-all.bash --timeout=15m to match CI.
  • Enterprise licensing — modules under enterprise/ use different licenses; do not copy code into other parts of the SDK without checking.

Development Workflow

  1. Pre-push verification. From the repo root, run in order:

    • make tidy-all (only if dependencies changed)
    • make build
    • make lint (depends on make lint-install; the first run will install the linter)
    • make test (or make test-unit)

    Fix any failures locally before pushing.

  2. Protobuf changes. Run make proto-all (format, lint, generate). Requires Docker and the proto-builder image. After proto changes, run make build and make test to ensure nothing is broken.
  3. Mocks. If you add or change interfaces that require mocks, run make mocks before pushing.
  4. Lint fixes. Run make lint-fix to auto-fix lint issues.
  5. Enterprise tests. When changing enterprise modules, also run make enterprise-all-test (or make enterprise-poa-test / make enterprise-group-test).

make all (tools build lint test vulncheck) is the full local check matching CI; use it before requesting review on a large change.

Changelog

  • Add entries to CHANGELOG.md under the ## UNRELEASED section.
  • Format: * (tag) [#PR-number](https://github.com/cosmos/cosmos-sdk/pull/PR-number) message
    • Example: * (x/staking) [#12345](https://github.com/cosmos/cosmos-sdk/pull/12345) Fix validator power calculation
  • Tags indicate the affected area: (x/bank), (store), (baseapp), (enterprise/poa), etc.
  • Stanzas (use the appropriate one): Features, Improvements, Deprecated, Bug Fixes, Breaking Changes (top-level umbrella), Client Breaking, CLI Breaking, API Breaking, State Machine Breaking.
  • For breaking changes, also add an entry to UPGRADING.md.
  • See the header of CHANGELOG.md for full formatting rules.

Commit Messages

  • Follow the Conventional Commits specification. Common types: feat, fix, docs, test, deps, chore.
  • Include the proposed commit message in the pull request description when opening a PR.

Pull Request Workflow

Before requesting review:

  • Pre-push verification passes (see Development Workflow)
  • Changelog entry added under ## UNRELEASED for user-facing or notable changes
  • UPGRADING.md entry added for breaking changes
  • CI is green (build, lint, tests)
  • PR is focused — split unrelated changes into separate PRs

Enterprise Modules

  • Located in enterprise/ (e.g. enterprise/poa, enterprise/group).
  • Each has its own go.mod and Makefile. Use make enterprise-<module>-<target> or make enterprise-all-<target>.
  • Different licensing — review the LICENSE file in each enterprise module before use or copying code.
  • Tests: make enterprise-poa-test or make enterprise-group-test.

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.

Check your setup, free