chore: add initial AGENTS.md
#3896
Conversation
|
@iiio2 is attempting to deploy a commit to the Nitro Team on Vercel. A member of the Team first needs to authorize it. |
📝 WalkthroughWalkthroughAdded two documentation files: Changes
Estimated code review effort🎯 1 (Trivial) | ⏱️ ~3 minutes Pre-merge checks and finishing touches❌ Failed checks (1 warning)
✅ Passed checks (2 passed)
✨ Finishing touches
🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 0
🧹 Nitpick comments (3)
CLAUDE.md (1)
7-7: Hyphenate compound modifier for consistency.Line 7 uses "next generation" where the hyphenated form "next-generation" is more appropriate for compound adjectives modifying "server toolkit."
🔎 Proposed fix
- Nitro is a next generation server toolkit. This is a monorepo using pnpm workspaces. + Nitro is a next-generation server toolkit. This is a monorepo using pnpm workspaces.AGENTS.md (2)
7-7: Hyphenate compound modifier for consistency.Line 7 uses "next generation" where the hyphenated form "next-generation" is more appropriate for compound adjectives modifying "server toolkit."
🔎 Proposed fix
- Nitro is a next generation server toolkit. This is a monorepo using pnpm workspaces with the following key characteristics: + Nitro is a next-generation server toolkit. This is a monorepo using pnpm workspaces with the following key characteristics:
32-48: Code style guidelines and workflows are practical.The documentation emphasizes ESM-first approach, automatic linting with
pnpm lint:fix, and pattern-following conventions. The Common Workflows section effectively explains the documentation workflow, though it could potentially be expanded with examples of other common tasks (e.g., adding features, testing, releasing) if you anticipate different use cases.Consider expanding the "Common Workflows" section with additional scenarios (e.g., adding a feature, running tests, handling breaking changes) if AI agents frequently work on tasks beyond documentation. This would reduce context-gathering time for more complex workflows.
📜 Review details
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (2)
AGENTS.mdCLAUDE.md
🧰 Additional context used
🪛 LanguageTool
CLAUDE.md
[grammar] ~7-~7: Use a hyphen to join words.
Context: .... ## Codebase Overview Nitro is a next generation server toolkit. This is a mon...
(QB_NEW_EN_HYPHEN)
AGENTS.md
[grammar] ~7-~7: Use a hyphen to join words.
Context: ...e. ## Project Overview Nitro is a next generation server toolkit. This is a mon...
(QB_NEW_EN_HYPHEN)
⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (3)
- GitHub Check: tests-rollup (windows-latest)
- GitHub Check: tests-rollup (ubuntu-latest)
- GitHub Check: tests-rolldown (windows-latest)
🔇 Additional comments (2)
CLAUDE.md (1)
3-11: Document structure and references look good.The file appropriately introduces Claude Code users to the codebase and directs them to the comprehensive AGENTS.md guide for detailed workflows and conventions.
AGENTS.md (1)
14-31: Setup and directory documentation is well-organized.The project structure, required Node versions, and key scripts are clearly documented. This provides essential context for AI agents to understand the build environment and common development tasks.
There was a problem hiding this comment.
Actionable comments posted: 1
📜 Review details
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (2)
AGENTS.mdCLAUDE.md
🧰 Additional context used
🪛 LanguageTool
AGENTS.md
[style] ~17-~17: Three successive sentences begin with the same word. Consider rewording the sentence or use a thesaurus to find a synonym.
Context: ...npm installto install dependencies. - Runpnpm build --stub` to prepare developm...
(ENGLISH_WORD_REPEAT_BEGINNING_RULE)
⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (3)
- GitHub Check: tests-rolldown (windows-latest)
- GitHub Check: tests-rollup (windows-latest)
- GitHub Check: tests-rollup (ubuntu-latest)
🔇 Additional comments (2)
AGENTS.md (1)
1-75: Comprehensive and well-organized AI agent guide.The guide effectively covers project identity, setup, repository structure, and development conventions. It provides clear, actionable guidance for AI agents contributing to Nitro. The structure is logical and information is appropriately scoped to support informed decision-making during development and code review.
Please verify that the technical instructions are current and accurate:
- Node version requirement (>= 22)
- Package manager (
pnpm) andcorepacksetup- Key scripts and their purposes
- Build process (
pnpm build --stub)- Repository structure paths
If any details have changed since documentation creation, please update accordingly to prevent AI agents from receiving stale guidance.
CLAUDE.md (1)
1-1: Clarify the purpose and mechanism of the@AGENTS.mdreference.The file contains only a reference to
AGENTS.md. Please clarify:
- What system or mechanism does
@AGENTS.mduse (e.g., Markdown reference, documentation system feature, custom convention)?- Why is a separate
CLAUDE.mdfile needed instead of directly documenting inAGENTS.mdor linking via standard Markdown/HTML?- Is this pattern consistent with other reference files in the repository?
This will help ensure the approach is aligned with the project's documentation conventions and that the intent is clear to contributors and AI agents.
| - Run `corepack enable` to ensure `pnpm` is available. | ||
| - Run `pnpm install` to install dependencies. | ||
| - Run `pnpm build --stub` to prepare development mode. |
There was a problem hiding this comment.
Reduce repetition of "Run" at the beginning of consecutive sentences.
Lines 15–17 each start with "Run". Consider varying the phrasing to improve readability and flow.
🔎 Suggested revision
- Run `corepack enable` to ensure `pnpm` is available.
- Run `pnpm install` to install dependencies.
- Run `pnpm build --stub` to prepare development mode.
+ First, run `corepack enable` to ensure `pnpm` is available.
+ Then, run `pnpm install` to install dependencies.
+ Finally, run `pnpm build --stub` to prepare development mode.📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| - Run `corepack enable` to ensure `pnpm` is available. | |
| - Run `pnpm install` to install dependencies. | |
| - Run `pnpm build --stub` to prepare development mode. | |
| - First, run `corepack enable` to ensure `pnpm` is available. | |
| - Then, run `pnpm install` to install dependencies. | |
| - Finally, run `pnpm build --stub` to prepare development mode. |
🧰 Tools
🪛 LanguageTool
[style] ~17-~17: Three successive sentences begin with the same word. Consider rewording the sentence or use a thesaurus to find a synonym.
Context: ...npm installto install dependencies. - Runpnpm build --stub` to prepare developm...
(ENGLISH_WORD_REPEAT_BEGINNING_RULE)
🤖 Prompt for AI Agents
In AGENTS.md around lines 15 to 17, the three consecutive lines all start with
"Run", creating repetitive phrasing; reword them so each instruction varies in
verb/structure while keeping the same meaning — for example, use "Enable
corepack to make pnpm available.", "Install dependencies with pnpm install.",
and "Build for development with pnpm build --stub." — ensure tone and imperative
style remain consistent with the surrounding document.
There was a problem hiding this comment.
Actionable comments posted: 1
🧹 Nitpick comments (2)
AGENTS.md (2)
56-60: Optional refactoring: Reduce "Changes in" repetition for improved flow.The bullet points repeat "Changes in" at the start of each line, which can be condensed for brevity while maintaining clarity.
🔎 Suggested revision
- Changes in `src/runtime` are bundled and run across all deployment targets. - Changes in `src/build` affect build output and performance. - Changes in `src/presets` affect specific deployment platforms. - Changes in `src/config` affect default behavior. + `src/runtime` changes are bundled and run across all deployment targets. + `src/build` changes affect build output and performance. + `src/presets` changes affect specific deployment platforms. + `src/config` changes affect default behavior.
109-111: Optional: Vary sentence structure in development workflow steps.Lines 4–6 start with "Run", creating slight repetition. Consider varying phrasing while maintaining the imperative instruction style.
🔎 Suggested revision
4. Run `pnpm lint:fix`. - 5. Run `pnpm test:types`. - 6. Run `pnpm vitest run`. + 5. Execute `pnpm test:types`. + 6. Complete the final test run with `pnpm vitest run`.Alternatively, renumber and consolidate where appropriate:
4. Run `pnpm lint:fix`. - 5. Run `pnpm test:types`. - 6. Run `pnpm vitest run`. + 5. Type-check with `pnpm test:types` and run final tests via `pnpm vitest run`.
📜 Review details
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (1)
AGENTS.md
🧰 Additional context used
🧠 Learnings (1)
📚 Learning: 2025-12-03T19:09:13.905Z
Learnt from: medz
Repo: nitrojs/nitro PR: 3834
File: src/presets/cloudflare/server-entry.ts:63-63
Timestamp: 2025-12-03T19:09:13.905Z
Learning: In the Nitro Cloudflare preset (src/presets/cloudflare/server-entry.ts), native errors from oxc-parser and Node.js readFile operations should be allowed to bubble up naturally without wrapping, as their native error messages are more user-friendly and provide better diagnostic information.
Applied to files:
AGENTS.md
🪛 LanguageTool
AGENTS.md
[style] ~17-~17: Three successive sentences begin with the same word. Consider rewording the sentence or use a thesaurus to find a synonym.
Context: ...npm installto install dependencies. - Runpnpm build --stub` to prepare developm...
(ENGLISH_WORD_REPEAT_BEGINNING_RULE)
[style] ~57-~57: Three successive sentences begin with the same word. Consider rewording the sentence or use a thesaurus to find a synonym.
Context: ... affect build output and performance. - Changes in src/presets affect specific deploy...
(ENGLISH_WORD_REPEAT_BEGINNING_RULE)
[style] ~58-~58: Three successive sentences begin with the same word. Consider rewording the sentence or use a thesaurus to find a synonym.
Context: ...affect specific deployment platforms. - Changes in src/config affect default behavior...
(ENGLISH_WORD_REPEAT_BEGINNING_RULE)
[grammar] ~76-~76: Use a hyphen to join words.
Context: ...Keep bundle size minimal and side-effect free. ## Testing Strategy ### Test Str...
(QB_NEW_EN_HYPHEN)
[style] ~111-~111: Three successive sentences begin with the same word. Consider rewording the sentence or use a thesaurus to find a synonym.
Context: ...lint:fix. 5. Run pnpm test:types. 6. Run pnpm vitest run`. ## Contribution Pri...
(ENGLISH_WORD_REPEAT_BEGINNING_RULE)
[style] ~136-~136: Three successive sentences begin with the same word. Consider rewording the sentence or use a thesaurus to find a synonym.
Context: ...consoleonly insrc/runtime/` code. - Use warnings for recoverable situations; th...
(ENGLISH_WORD_REPEAT_BEGINNING_RULE)
⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (2)
- GitHub Check: tests-rollup (ubuntu-latest)
- GitHub Check: tests-rollup (windows-latest)
🔇 Additional comments (1)
AGENTS.md (1)
15-17: Address the previously flagged repetition of "Run" at the start of each line.This issue was raised in the past review but not resolved. Vary the sentence structure to improve readability.
🔎 Suggested revision
- Run `corepack enable` to ensure `pnpm` is available. - Run `pnpm install` to install dependencies. - Run `pnpm build --stub` to prepare development mode. + First, run `corepack enable` to ensure `pnpm` is available. + Then, run `pnpm install` to install dependencies. + Finally, run `pnpm build --stub` to prepare development mode.
| - **Don't use Node.js-specific APIs** (unless behind runtime checks). | ||
| - Prefer **Web APIs** (fetch, Request, Response, URL, etc.). | ||
| - Only use `console` for logging (no `consola` in runtime). | ||
| - Keep bundle size minimal and side-effect free. |
There was a problem hiding this comment.
🛠️ Refactor suggestion | 🟠 Major
Fix hyphenation in compound adjective.
Compound adjectives should be hyphenated when modifying a noun. Change "side-effect free" to "side-effect-free".
🔎 Suggested fix
- Keep bundle size minimal and side-effect free.
+ Keep bundle size minimal and side-effect-free.📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| - Keep bundle size minimal and side-effect free. | |
| - Keep bundle size minimal and side-effect-free. |
🧰 Tools
🪛 LanguageTool
[grammar] ~76-~76: Use a hyphen to join words.
Context: ...Keep bundle size minimal and side-effect free. ## Testing Strategy ### Test Str...
(QB_NEW_EN_HYPHEN)
🤖 Prompt for AI Agents
In AGENTS.md around line 76, the compound adjective "side-effect free" should be
hyphenated when modifying a noun; change the phrase to "side-effect-free" so the
line reads "Keep bundle size minimal and side-effect-free."
|
Thanks! |
|
Thanks @pi0 . ❤️ |
2 participants
Actually I'm seeing such thing in many oss projects recently on ai agent guide. I thought maybe such thing we can also implement.