From 4eb9791a3e3fe4fc265dfd05cb0016466d28d75b Mon Sep 17 00:00:00 2001 From: DuskWarden Date: Sat, 18 Apr 2026 17:18:38 +0530 Subject: [PATCH 1/2] docs: add AGENTS.md for AI-facing documentation --- AGENTS.md | 141 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 141 insertions(+) create mode 100644 AGENTS.md diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 000000000000..01bcaab26f58 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,141 @@ +# AsyncAPI Website — AI Agent Guidelines + +Guidelines for AI coding assistants working on this repository. Read this before generating any code or PRs. + +## Project Overview + +- **Framework:** Next.js (Pages Router) with TypeScript (strict mode) +- **Styling:** Tailwind CSS 3 with a custom theme defined in `tailwind.config.ts` +- **Content:** Blog posts and docs are written in MDX/MD inside the `markdown/` directory +- **Testing:** Jest for unit/script tests, Cypress for E2E +- **Deployment:** Netlify (static site + edge functions) +- **i18n:** next-i18next with locales `en`, `de`, `zh_cn` +- **Component docs:** Storybook 8 + +## Project Structure + +``` +pages/ # Next.js page routes (includes [lang]/ for i18n) +components/ # Reusable React/TypeScript UI components +markdown/ # Blog posts, docs, and about content (MDX/MD) +scripts/ # Build and data-generation scripts (TypeScript) +config/ # JSON schemas, data files, finance configs +types/ # TypeScript type definitions +utils/ # Shared utility functions +context/ # React Context providers +styles/ # Global CSS and Tailwind imports +tests/ # Jest test files +cypress/ # Cypress E2E test files +public/ # Static assets, images, i18n locale JSON files +netlify/ # Netlify edge functions +.github/ # GitHub Actions workflows +``` + +## Contribution Workflow + +1. **Open an issue first** and get it approved before starting any PR, unless its a typo or obvious fix +2. **One PR = one thing** — don't bundle multiple features or fixes into a single PR +3. PR titles **must** follow Conventional Commits: + - `feat:` `fix:` `docs:` `chore:` `test:` `refactor:` + - Use imperative mood (e.g. "add helper function", not "added helper function") +4. PR description should include `Resolves #` or `Fixes #` + +## Dev Commands + +```bash +npm install # Install dependencies +npm run dev # Start dev server +npm run build # Production build +npm run lint # Run ESLint +npm test # Run Jest tests +npx cypress run # Run Cypress E2E tests +``` + +Always run `npm run lint` before submitting. CI will fail on lint errors. + +## Code Style + +These are enforced by ESLint and will cause CI failures if not followed: + +- **Single quotes**, no trailing commas, semicolons required +- **Max line length:** 120 characters (className strings are exempt) +- **`import type`** must be used for type-only imports (enforced by `@typescript-eslint/consistent-type-imports`) +- **Import ordering** is enforced by `simple-import-sort` — let the linter auto-fix this, don't manually rearrange +- **No `console.log`** — `no-console` is set to error +- **Prefer `const`** and arrow callbacks +- **Functional components** — the codebase uses functional components throughout +- **Destructure props** in function signatures + +## Typography Components + +The project has a design system for text. **New components should use these instead of raw HTML heading/paragraph tags:** + +```tsx +// preferred +import Heading from '@/components/typography/Heading'; +import Paragraph from '@/components/typography/Paragraph'; + +Title +Body text +``` + +`Heading` accepts `level` (h1-h6) and `typeStyle` props from `@/types/typography/Heading`. +`Paragraph` accepts `typeStyle` from `@/types/typography/Paragraph`. + +## Tailwind Usage + +This project uses **custom design tokens** defined in `tailwind.config.ts`. Use these instead of default Tailwind values: + +**Colors** — use the project palette: +- `primary-100` through `primary-600` (purple tones) +- `secondary-100` through `secondary-600` (blue tones) +- `gray-50` through `gray-900` (custom gray scale) + +**Font sizes** — use the project scale: +- Headings: `text-heading-xs`, `text-heading-sm`, `text-heading-md`, `text-heading-lg`, `text-heading-xl` +- Body: `text-body-sm`, `text-body-md`, `text-body-lg` + +**Font families:** +- `font-heading` (Work Sans) +- `font-body` / `font-sans` (Inter) +- `font-mono` (Fira Code) + +## Testing Conventions + +- Jest tests go in `tests/` — test coverage is collected from `scripts/**/*.ts` +- Cypress E2E tests go in `cypress/` +- Use `data-testid` attributes for DOM hooks in components (e.g. `data-testid='Button-main'`) +- Naming: `data-testid='ComponentName-element'` + +## TypeScript Conventions + +- Props interfaces use JSDoc comments on each field +- Data shape interfaces use `I` prefix (e.g. `IBlogPost`, `IHeadProps`) +- Component props use descriptive names (e.g. `HeadingProps`, `ButtonProps`) +- Enum values are used for component variants (see `@/types/`) + +## Behavioral Guidelines + +When modifying existing code: + +- **Don't "improve" adjacent code** — touch only what the task requires +- **Match existing patterns** — even if you'd write it differently. Consistency over preference +- **Don't refactor what isn't broken** — if you spot unrelated issues, mention them, don't fix them in the same PR +- **Keep changes small** — if the scope grows beyond the original issue, suggest splitting into follow-up issues + +## Boundaries — Do Not Touch + +Unless explicitly asked: +- `package-lock.json` — only modify through `npm install` +- `.github/workflows/` — CI configuration +- `config/` JSON files — auto-generated data +- `public/locales/` — translation files require sync across all locales + +## Common Mistakes to Avoid + +- Using raw `

`–`

` or `

` tags instead of `Heading`/`Paragraph` components +- Using default Tailwind colors (e.g. `text-blue-500`) instead of project tokens (`text-primary-500`) +- Importing types without `import type` — this breaks the build +- Not running `npm run lint` before committing — import sort order alone causes many CI failures +- Bundling unrelated changes into one PR +- Opening a PR without a linked issue From 8f518aca99073ad6515ea1313f8918b4eff82844 Mon Sep 17 00:00:00 2001 From: DuskWarden Date: Sat, 18 Apr 2026 17:40:53 +0530 Subject: [PATCH 2/2] docs: address review feedback on AGENTS.md --- AGENTS.md | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 01bcaab26f58..d2e0456bd4f6 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -14,7 +14,7 @@ Guidelines for AI coding assistants working on this repository. Read this before ## Project Structure -``` +```text pages/ # Next.js page routes (includes [lang]/ for i18n) components/ # Reusable React/TypeScript UI components markdown/ # Blog posts, docs, and about content (MDX/MD) @@ -33,7 +33,7 @@ netlify/ # Netlify edge functions ## Contribution Workflow -1. **Open an issue first** and get it approved before starting any PR, unless its a typo or obvious fix +1. **Open an issue first** and get it approved before starting any PR, unless it's a typo or obvious fix 2. **One PR = one thing** — don't bundle multiple features or fixes into a single PR 3. PR titles **must** follow Conventional Commits: - `feat:` `fix:` `docs:` `chore:` `test:` `refactor:` @@ -109,10 +109,10 @@ This project uses **custom design tokens** defined in `tailwind.config.ts`. Use ## TypeScript Conventions -- Props interfaces use JSDoc comments on each field -- Data shape interfaces use `I` prefix (e.g. `IBlogPost`, `IHeadProps`) -- Component props use descriptive names (e.g. `HeadingProps`, `ButtonProps`) -- Enum values are used for component variants (see `@/types/`) +- Prefer adding JSDoc comments to fields in props types/interfaces +- Data shape types/interfaces often use an `I` prefix (e.g. `IBlogPost`, `IHeadProps`) +- Prefer descriptive names for component props types/interfaces (e.g. `HeadingProps`, `ButtonProps`) +- Enum values are commonly used for component variants (see `@/types/`) ## Behavioral Guidelines @@ -128,7 +128,7 @@ When modifying existing code: Unless explicitly asked: - `package-lock.json` — only modify through `npm install` - `.github/workflows/` — CI configuration -- `config/` JSON files — auto-generated data +- Auto-generated config outputs (`config/tools.json`, `config/all-tags.json`, `config/posts.json`, etc.) — other `config/` files may be manually maintained - `public/locales/` — translation files require sync across all locales ## Common Mistakes to Avoid