Skip to content

docs: Add AGENTS.md to allow LLMs to work effectively with the codebase #4481

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 1 commit into
base: main
Choose a base branch
from
Open

docs: Add AGENTS.md to allow LLMs to work effectively with the codebase #4481

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
33 changes: 33 additions & 0 deletions AGENTS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,33 @@
# AGENTS.md

## Project Overview
This file contains essential configuration and commands for LLM agents to work effectively with this codebase. It serves as a reference for automated agents and human developers.

## Build, Lint, Test Commands
- **Build**: `make node` (Go guardian), `npm run build` (JS/TS projects), `forge build` (Solidity)
- **Lint**: `./scripts/lint.sh lint` (Go + spellcheck), `npm run lint` (TypeScript projects)
- **Test**: `npm test` (JS/TS), `jest --verbose` (specific tests), `DEV=true NETWORK=DEVNET jest --verbose` (SDK tests)
- **Single test**: `jest path/to/test.js -t "test name"` or `npm test -- --testNamePattern="pattern"`
- **Format**: `./scripts/lint.sh format` (Go), `./scripts/lint.sh -w format` (auto-fix)

## Code Style Guidelines
- **Go**: Use `goimports`, follow `.golangci.yml` rules, camelCase for unexported, PascalCase for exported
- **TypeScript**: Use existing project conventions, prefer `import` over `require`, explicit types over `any`
- **Solidity**: Follow existing patterns in `ethereum/contracts/`, use Forge for builds
- **Imports**: Organize by standard lib, external packages, internal packages (Go); relative imports last (TS)
- **Error handling**: Always handle errors explicitly, use proper error types, no silent failures
- **Naming**: Descriptive names, avoid abbreviations, match existing patterns in codebase
- **Comments**: Follow [Go Doc Comments](https://go.dev/doc/comment) for Go, [TSDoc](https://tsdoc.org/) for TypeScript

## Development Workflow
- **Pre-commit**: Run `./scripts/lint.sh -d format` and `./scripts/lint.sh lint` before committing
- **Commits**: Small atomic commits with meaningful messages, prefix with component name (e.g., "node: fix bug")
- **PRs**: All features require GitHub issue discussion first, complex features need design docs
- **Quality focus**: Optimize for reading over writing, meaningful commit messages, useful comments
- **Dependencies**: Document benefits vs security/compatibility when updating dependencies

## Testing by Component
- **Guardian Node**: `cd node && make test` (tests in `./node/**/*_test.go`)
- **Ethereum**: `cd ethereum && make test` (tests in `./ethereum/test/`)
- **Solana**: `cd solana && make test` (tests in `./solana/bridge/program/tests/`)
- **Cosmwasm/Algorand**: `cd {component} && make test`
6 changes: 6 additions & 0 deletions CONTRIBUTING.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -152,3 +152,9 @@ Places to find out more about existing test coverage and how to run those tests:
- Run: `cd algorand && make test`

The best place to understand how we invoke these tests via GitHub Actions on every commit can be found via `./.github/workflows/*.yml` and the best place to observe the results of these builds can be found via [https://github.com/wormhole-foundation/wormhole/actions](https://github.com/wormhole-foundation/wormhole/actions).

## Working with LLMs/Agents

The repository contains an [AGENTS.md](./AGENTS.md) file that can be used to direct LLMs to work effectively with the repository.
Rather than adding a custom markdown file for the wide range of LLM tools that exist, we've opted to use AGENTS.md
as it is relatively general (https://agents.md/). Its contents can be copied into e.g. CLAUDE.md or cursor rules etc. depending on the developer's taste.
Loading