Skip to content

AGENTS.md

Latest commit

 

History

History
130 lines (89 loc) · 6.25 KB

AGENTS.md

File metadata and controls

130 lines (89 loc) · 6.25 KB
Raw

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
pnpm lint:trailing-slash Find internal links missing a /
pnpm lint:trailing-slash:fix Add the missing trailing slashes

Internal links

next.config.ts sets trailingSlash: true, so an internal link written without a trailing slash is served a 308 redirect before the page loads. Write internal links in their canonical form (/product/issues/, not /product/issues). A pre-commit hook fixes staged files automatically, and pnpm lint:trailing-slash:fix fixes the whole repo.

Exceptions the tooling already handles: versioned pages (__v10.7.0) invert the rule and must not get a trailing slash; links whose path already ends in a slash before a query string (/platform-redirect/?next=%2Fx%2F) are correct as-is; and attributes that carry filesystem paths or config values rather than URLs (includePath, path, endpoint) are left alone, as is anything inside a code block.

If you hit a link that genuinely must stay bare, add a trailing-slash-ignore marker in a comment on the link's line or the line above it. Both the hook and CI honor it:

{/* trailing-slash-ignore */}
See [the thing](/foo).

To bypass the hook once without marking the file, use SKIP=trailing-slashes git commit. That only affects your local commit — CI will still flag the link, so prefer the marker for anything permanent.

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.

Agent Skills

Managed skills in .agents/skills/ are not checked in. Run make develop (or npx -y @sentry/dotagents install) to install them before relying on skills like /brand-guidelines or /commit.

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.