Skip to content

Commit 4eb9791

Browse files
sammy200-uisammy200-ui
committed
docs: add AGENTS.md for AI-facing documentation
1 parent a267f1e commit 4eb9791

1 file changed

Lines changed: 141 additions & 0 deletions

File tree

‎AGENTS.md‎

Lines changed: 141 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,141 @@
1+
# AsyncAPI Website — AI Agent Guidelines
2+
3+
Guidelines for AI coding assistants working on this repository. Read this before generating any code or PRs.
4+
5+
## Project Overview
6+
7+
- **Framework:** Next.js (Pages Router) with TypeScript (strict mode)
8+
- **Styling:** Tailwind CSS 3 with a custom theme defined in `tailwind.config.ts`
9+
- **Content:** Blog posts and docs are written in MDX/MD inside the `markdown/` directory
10+
- **Testing:** Jest for unit/script tests, Cypress for E2E
11+
- **Deployment:** Netlify (static site + edge functions)
12+
- **i18n:** next-i18next with locales `en`, `de`, `zh_cn`
13+
- **Component docs:** Storybook 8
14+
15+
## Project Structure
16+
17+
```
18+
pages/ # Next.js page routes (includes [lang]/ for i18n)
19+
components/ # Reusable React/TypeScript UI components
20+
markdown/ # Blog posts, docs, and about content (MDX/MD)
21+
scripts/ # Build and data-generation scripts (TypeScript)
22+
config/ # JSON schemas, data files, finance configs
23+
types/ # TypeScript type definitions
24+
utils/ # Shared utility functions
25+
context/ # React Context providers
26+
styles/ # Global CSS and Tailwind imports
27+
tests/ # Jest test files
28+
cypress/ # Cypress E2E test files
29+
public/ # Static assets, images, i18n locale JSON files
30+
netlify/ # Netlify edge functions
31+
.github/ # GitHub Actions workflows
32+
```
33+
34+
## Contribution Workflow
35+
36+
1. **Open an issue first** and get it approved before starting any PR, unless its a typo or obvious fix
37+
2. **One PR = one thing** — don't bundle multiple features or fixes into a single PR
38+
3. PR titles **must** follow Conventional Commits:
39+
- `feat:` `fix:` `docs:` `chore:` `test:` `refactor:`
40+
- Use imperative mood (e.g. "add helper function", not "added helper function")
41+
4. PR description should include `Resolves #<issue-number>` or `Fixes #<issue-number>`
42+
43+
## Dev Commands
44+
45+
```bash
46+
npm install # Install dependencies
47+
npm run dev # Start dev server
48+
npm run build # Production build
49+
npm run lint # Run ESLint
50+
npm test # Run Jest tests
51+
npx cypress run # Run Cypress E2E tests
52+
```
53+
54+
Always run `npm run lint` before submitting. CI will fail on lint errors.
55+
56+
## Code Style
57+
58+
These are enforced by ESLint and will cause CI failures if not followed:
59+
60+
- **Single quotes**, no trailing commas, semicolons required
61+
- **Max line length:** 120 characters (className strings are exempt)
62+
- **`import type`** must be used for type-only imports (enforced by `@typescript-eslint/consistent-type-imports`)
63+
- **Import ordering** is enforced by `simple-import-sort` — let the linter auto-fix this, don't manually rearrange
64+
- **No `console.log`** — `no-console` is set to error
65+
- **Prefer `const`** and arrow callbacks
66+
- **Functional components** — the codebase uses functional components throughout
67+
- **Destructure props** in function signatures
68+
69+
## Typography Components
70+
71+
The project has a design system for text. **New components should use these instead of raw HTML heading/paragraph tags:**
72+
73+
```tsx
74+
// preferred
75+
import Heading from '@/components/typography/Heading';
76+
import Paragraph from '@/components/typography/Paragraph';
77+
78+
<Heading level={HeadingLevel.h2} typeStyle={HeadingTypeStyle.md}>Title</Heading>
79+
<Paragraph typeStyle={ParagraphTypeStyle.md}>Body text</Paragraph>
80+
```
81+
82+
`Heading` accepts `level` (h1-h6) and `typeStyle` props from `@/types/typography/Heading`.
83+
`Paragraph` accepts `typeStyle` from `@/types/typography/Paragraph`.
84+
85+
## Tailwind Usage
86+
87+
This project uses **custom design tokens** defined in `tailwind.config.ts`. Use these instead of default Tailwind values:
88+
89+
**Colors** — use the project palette:
90+
- `primary-100` through `primary-600` (purple tones)
91+
- `secondary-100` through `secondary-600` (blue tones)
92+
- `gray-50` through `gray-900` (custom gray scale)
93+
94+
**Font sizes** — use the project scale:
95+
- Headings: `text-heading-xs`, `text-heading-sm`, `text-heading-md`, `text-heading-lg`, `text-heading-xl`
96+
- Body: `text-body-sm`, `text-body-md`, `text-body-lg`
97+
98+
**Font families:**
99+
- `font-heading` (Work Sans)
100+
- `font-body` / `font-sans` (Inter)
101+
- `font-mono` (Fira Code)
102+
103+
## Testing Conventions
104+
105+
- Jest tests go in `tests/` — test coverage is collected from `scripts/**/*.ts`
106+
- Cypress E2E tests go in `cypress/`
107+
- Use `data-testid` attributes for DOM hooks in components (e.g. `data-testid='Button-main'`)
108+
- Naming: `data-testid='ComponentName-element'`
109+
110+
## TypeScript Conventions
111+
112+
- Props interfaces use JSDoc comments on each field
113+
- Data shape interfaces use `I` prefix (e.g. `IBlogPost`, `IHeadProps`)
114+
- Component props use descriptive names (e.g. `HeadingProps`, `ButtonProps`)
115+
- Enum values are used for component variants (see `@/types/`)
116+
117+
## Behavioral Guidelines
118+
119+
When modifying existing code:
120+
121+
- **Don't "improve" adjacent code** — touch only what the task requires
122+
- **Match existing patterns** — even if you'd write it differently. Consistency over preference
123+
- **Don't refactor what isn't broken** — if you spot unrelated issues, mention them, don't fix them in the same PR
124+
- **Keep changes small** — if the scope grows beyond the original issue, suggest splitting into follow-up issues
125+
126+
## Boundaries — Do Not Touch
127+
128+
Unless explicitly asked:
129+
- `package-lock.json` — only modify through `npm install`
130+
- `.github/workflows/` — CI configuration
131+
- `config/` JSON files — auto-generated data
132+
- `public/locales/` — translation files require sync across all locales
133+
134+
## Common Mistakes to Avoid
135+
136+
- Using raw `<h1>`–`<h6>` or `<p>` tags instead of `Heading`/`Paragraph` components
137+
- Using default Tailwind colors (e.g. `text-blue-500`) instead of project tokens (`text-primary-500`)
138+
- Importing types without `import type` — this breaks the build
139+
- Not running `npm run lint` before committing — import sort order alone causes many CI failures
140+
- Bundling unrelated changes into one PR
141+
- Opening a PR without a linked issue

0 commit comments

Comments
 (0)