Skip to content

Add AGENTS.md #1647

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

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

Add AGENTS.md #1647

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
62 changes: 62 additions & 0 deletions AGENTS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,62 @@
# ENSNode

ENSNode is a multichain ENS indexer monorepo. It indexes ENS names across multiple chains (mainnet, Basenames, Lineanames, 3DNS) and exposes them via GraphQL and REST APIs.

## Monorepo Structure

- `apps/ensindexer` — Blockchain indexer powered by Ponder
- `apps/ensapi` — ENS API server (GraphQL and REST, Hono)
- `apps/ensadmin` — Dashboard for navigating indexed ENS state (Next.js)
- `apps/ensrainbow` — Label healing service: recovers labels from labelHashes (Hono)
- `apps/fallback-ensapi` — AWS Lambda fallback that proxies ENS Subgraph requests when ENSApi is unhealthy
- `packages/ensnode-sdk` — SDK for interacting with ENSNode
- `packages/ensnode-react` — React hooks and providers for ENSNode API
- `packages/ensnode-schema` — Shared Drizzle schema definitions
- `packages/ensrainbow-sdk` — SDK for interacting with ENSRainbow
- `packages/datasources` — Catalog of chain datasources (contracts, start blocks, event filters)
- `packages/ponder-subgraph` — Hono middleware for Subgraph-compatible GraphQL
- `packages/ponder-sdk` — Utility library for interacting with Ponder apps and data
- `packages/ponder-metadata` — Hono middleware that exposes Ponder app metadata to clients
- `packages/ens-referrals` — Utilities for ENS Referrals
- `packages/namehash-ui` — UI components for NameHash Labs apps
- `packages/shared-configs` — Shared TypeScript configurations
- `docs/ensnode.io` — Documentation site (Astro/Starlight)

## Tech Stack

- **Language:** TypeScript
- **Package manager:** pnpm (workspaces with catalog for dependency versioning)
- **API framework:** Hono
- **Indexer framework:** Ponder
- **Validation:** Zod
- **ORM:** Drizzle
- **Linting/formatting:** Biome
- **Testing:** Vitest
- **Build:** tsup, tsx

## Testing

- Tests are colocated with source files (e.g. `foo.test.ts` next to `foo.ts`).
- Use the `*.test.ts` naming convention. Do not use `*.spec.ts`.
- Use `describe`/`it` blocks with `expect` assertions.
- Use `vi.mock()` for module mocking and `vi.fn()` for function stubs.
- Each app and package has its own `vitest.config.ts`.
Comment on lines +37 to +43
Copy link

@coderabbitai coderabbitai bot Feb 17, 2026 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🛠️ Refactor suggestion | 🟠 Major

🧩 Analysis chain

🏁 Script executed:

# First, locate and examine the AGENTS.md file
find . -name "AGENTS.md" -type f

Repository: namehash/ensnode

Length of output: 71

🏁 Script executed:

# Get root package.json scripts
cat package.json | head -50

Repository: namehash/ensnode

Length of output: 2122

🏁 Script executed:

# Look at app package examples
fd "package.json" apps/ | head -3 | xargs -I {} sh -c 'echo "--- {} ---"; head -30 {}'

Repository: namehash/ensnode

Length of output: 3023

🏁 Script executed:

# Read the full AGENTS.md file
cat AGENTS.md

Repository: namehash/ensnode

Length of output: 3031

🏁 Script executed:

# Count lines to confirm structure
wc -l AGENTS.md

Repository: namehash/ensnode

Length of output: 72

Add a "Commands" section — AI agents need explicit commands to self-verify changes.

AGENTS.md is consumed by AI coding agents that need executable commands to validate their work. The testing conventions are documented but there's no guidance on how to invoke them, and Biome is listed in the tech stack but never explained how to run.

Add a section like:

Suggested Commands section 
## Commands

# Install dependencies
pnpm install

# Run all tests
pnpm test

# Run tests for a specific package
pnpm --filter <package-name> test

# Lint and format (Biome)
pnpm lint                  # auto-fix all files
pnpm lint:ci               # CI mode (fails if changes needed)

# Type check
pnpm typecheck

Adjust exact commands to match the root package.json scripts or add per-package examples if needed. The key is making invocation explicit so agents (and developers) don't have to guess.

🤖 Prompt for AI Agents 
Verify each finding against the current code and only fix it if needed.

In `@AGENTS.md` around lines 37 - 43, Add a new "Commands" section to AGENTS.md
that provides explicit, runnable commands for agents and devs to validate
changes: include install (pnpm install), run all tests (pnpm test), run
package-scoped tests (pnpm --filter <package-name> test), lint/format with Biome
(pnpm lint and pnpm lint:ci), and type checking (pnpm typecheck); ensure the
section header is "Commands" and mention Biome as the linter/formatter so agents
know which script to call and adjust any commands to match the root package.json
script names if they differ.

Copy link
Member

@lightwalker-eth lightwalker-eth Feb 18, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@djstrong Appreciate your advice on this suggestion from coderabbit.

Copy link

@coderabbitai coderabbitai bot Feb 18, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Seems like the humans are having a chat. I'll hop back into my burrow for now. If you need me again, just tag @coderabbitai in a new comment, and I'll come hopping out!


## Documentation & DRY

- Do not duplicate definitions across multiple locations. Duplication creates a significant maintenance burden.
- Ensure documentation resides at the correct place and the correct layer of responsibility.
- Use type aliases to document invariants. Each invariant MUST be documented exactly once, on its type alias.

## Code Comments

- Do not add JSDoc `@returns` tags that merely restate the method summary (e.g. "returns the X" when the description already says "Get the X"). Remove such redundancy during PR review.
- Maintain comment consistency within a file: if most types, schemas, or declarations lack comments, do not add a comment to a single one. Address the inconsistency during PR review.

## Error Handling

- Fail fast and loudly on invalid inputs.

## Workflow

- All changes require changesets: https://ensnode.io/docs/contributing/prs/#changesets
Copy link

Copilot AI Feb 17, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The statement "All changes require changesets" is inconsistent with the repo’s documented changeset policy. The contributing docs explicitly say changesets should not be created for every PR/logical change, and that a PR with no qualifying logical changes should not include a changeset. Please reword this bullet to match the criteria (e.g., “Add a changeset when your PR includes a logical change that should bump versions or be communicated in release notes”).

Suggested change
- All changes require changesets: https://ensnode.io/docs/contributing/prs/#changesets
- Add a changeset when your PR includes a logical change that should bump versions or be communicated in release notes: https://ensnode.io/docs/contributing/prs/#changesets

Copilot uses AI. Check for mistakes.
Copy link
Member

@lightwalker-eth lightwalker-eth Feb 18, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@djstrong This looks like good feedback from Copilot.