Skip to content

AGENTS.md

Latest commit

 

History

History
109 lines (76 loc) · 4.53 KB

AGENTS.md

File metadata and controls

109 lines (76 loc) · 4.53 KB

Agent Instructions

Package Manager

Use pnpm: pnpm install, pnpm dev, pnpm build, pnpm test

Development

  • pnpm dev - Start dev server with Sentry sidecar
  • pnpm dev:minimal - Start dev server without sidecar
  • pnpm build - Production build
  • pnpm test - Run tests with vitest
  • pnpm lint - Run all linters
  • pnpm lint:fix - Auto-fix lint issues

Tech Stack

  • Next.js 15 with App Router
  • React 19
  • TypeScript
  • Tailwind CSS
  • MDX for documentation content
  • Sentry SDK (@sentry/nextjs)

Project Structure

  • app/ - Next.js app router pages and layouts
  • src/ - Source code (components, utilities)
  • docs/ - MDX documentation content
  • develop-docs/ - Developer documentation (submodule)
  • includes/ - Reusable MDX includes
  • platform-includes/ - Platform-specific MDX content
  • public/ - Static assets

Code Style

  • ESLint + Prettier enforced via pre-commit hooks using prek
    • If you previously installed pre-commit and prek is available on your system, reinstall the Git shims with prek install -f.
  • Use TypeScript strict mode
  • Follow existing patterns in codebase

Testing

Run pnpm test for vitest. Tests live alongside source files or in __tests__ directories.

CLI Commands

Command Description
make develop Initial setup
make test Run tests
pnpm lint:ts TypeScript check
pnpm lint:eslint ESLint check
pnpm lint:prettier Prettier check

Repo UX / Generated files

next-env.d.ts is in .gitignore and is generated by Next.js when you run pnpm dev or pnpm build. When we upgrade to Next 15.5+, we can run next typegen in CI and in lint:ts so the file is generated before type-check.

Developer Documentation (develop-docs/)

When writing requirements in develop-docs/:

  1. Use RFC 2119 Keywords: Use "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" as defined in RFC 2119. These keywords MUST be written in uppercase and bold, for example: MUST, SHOULD, MAY.

  2. Add RFC 2119 Alert: When creating a new file with requirements, or adding requirements to an existing file, ensure the file has an Alert at the top (after frontmatter) to clarify RFC 2119 usage. If missing, add:

    <Alert>
  This document uses key words such as "MUST", "SHOULD", and "MAY" as defined
  in [RFC 2119](https://www.ietf.org/rfc/rfc2119.txt) to indicate requirement
  levels.
</Alert>

Content Authoring

  • ALWAYS run /brand-guidelines to audit any user-facing content before committing. See .agents/skills/brand-guidelines/SKILL.md
  • Use docs-review skill for Sentry style and voice review. See .claude/skills/docs-review/SKILL.md
  • Use technical-docs skill when writing or reviewing SDK documentation. See .claude/skills/technical-docs/SKILL.md

LLM-Friendly MD Exports

  • Every page at docs.sentry.io/<path> has a .md export at docs.sentry.io/<path>.md
  • scripts/generate-md-exports.mjs generates these as a post-build step
  • Frontmatter metadata (title, description, URL) is emitted as a YAML frontmatter block in MD exports — pages missing descriptions lose LLM relevance signal
  • MDX override templates live in md-overrides/
  • Architecture spec: specs/llm-friendly-docs.md

llms.txt

  • docs.sentry.io/llms.txt is the root LLM discovery index (follows llmstxt.org spec)
  • Auto-generated from public/doctree.json by scripts/generate-llms-txt.mjs
  • Run pnpm generate-llms-txt to regenerate, or it runs automatically as part of pnpm build
  • Includes: product description, AI agent instructions, platform/section index, links to agent skills at skills.sentry.dev

Sentry Product Skills (sentry-for-ai)

Skills for using Sentry (SDK setup, debugging, alerts) live in a separate repo: https://github.com/getsentry/sentry-for-ai. The skills in this repo (.claude/skills/, .agents/skills/) are for contributing to the docs. See SKILL.md at the repo root for a routing guide.

Plan Mode

  • Make the plan extremely concise. Sacrifice grammar for the sake of concision.
  • At the end of each plan, give me a list of unresolved questions to answer, if any.

Commit and Pull Request generation

When committing changes, use the Sentry commit skill if available.

For PRs, use .github/PULL_REQUEST_TEMPLATE.md. Also, use the Sentry pull request skill if available.