feat(config): Reorganize agent rules and instructions#683
Conversation
- Move project guidelines from CLAUDE.md to .agents/rules/base.md - Create browser-extension.md rule file for browser development - Consolidate GitHub release note guidelines into base.md - Add cross-references between rule files for better navigation - Update instructions to reference new rule structure This improves organization by separating core project rules from extension-specific and website-specific guidelines, making it easier for AI agents to apply the appropriate rules based on context. 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <noreply@anthropic.com>
WalkthroughThis update centralizes and restructures project guidelines by introducing a new comprehensive rules document at Changes
Sequence Diagram(s)sequenceDiagram
participant Contributor
participant Repo
participant Guidelines
Contributor->>Repo: Seeks project guidelines
Repo->>Guidelines: Points to .agents/rules/base.md
Contributor->>Guidelines: Reads unified rules
Guidelines-->>Contributor: Provides standards for code, PRs, commits, and reviews
Possibly related PRs
✨ Finishing Touches🧪 Generate Unit Tests
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. 🪧 TipsChatThere are 3 ways to chat with CodeRabbit:
SupportNeed help? Create a ticket on our support page for assistance with any issues or questions. Note: Be mindful of the bot's finite context window. It's strongly recommended to break down tasks such as reading entire modules into smaller chunks. For a focused discussion, use review comments to chat about specific files and their changes, instead of using the PR comments. CodeRabbit Commands (Invoked using PR comments)
Other keywords and placeholders
Documentation and Community
|
|
Claude finished @yamadashy's task —— View job PR Review: Agent Rules ReorganizationReviewing the reorganization of AI agent instructions and rule structure. Todo List
Review FeedbackThis PR successfully reorganizes AI agent instructions into a much more maintainable and scalable structure. Overall, this is a well-executed refactoring that significantly improves the codebase organization. ✅ Strengths & Best Practices1. Excellent Modular Architecture
2. Smart Content Consolidation
3. Strong Cross-Referencing System
4. Proper Metadata Usage
🔍 Architecture AnalysisDirectory Structure - The new
Content Migration - The migration from CLAUDE.md to base.md is thorough:
💡 Minor Suggestions for Improvement1. Consider Adding Table of Contents ## Table of Contents
- [Project Overview](#project-overview)
- [Coding Guidelines](#coding-guidelines)
- [Commit Messages](#commit-messages)
- [Dependencies and Testing](#dependencies-and-testing)2. Validate Cross-References 3. Documentation Consistency 🎯 Impact AssessmentMaintainability: ⭐⭐⭐⭐⭐
Scalability: ⭐⭐⭐⭐⭐
Developer Experience: ⭐⭐⭐⭐⭐
🔒 Security & Quality
VerdictThis is a high-quality refactoring that transforms a maintenance burden into a well-organized, scalable system. The reorganization follows software engineering best practices for modular design and separation of concerns. Recommendation: ✅ Approve - This PR significantly improves the codebase organization with no identified issues. The net reduction of 282 lines while maintaining functionality demonstrates excellent consolidation work. The new structure will make it much easier for AI agents to apply appropriate rules based on context, which was the primary goal of this reorganization. |
![gemini-code-assist[bot]](https://avatars.githubusercontent.com/in/956858?s=60&v=4){kind=small}
There was a problem hiding this comment.
Summary of Changes
Hello @yamadashy, I'm Gemini Code Assist1! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!
This pull request significantly refactors how AI agent instructions and project guidelines are organized within the repository. The primary goal is to enhance maintainability and ensure AI agents can more effectively apply context-specific rules by centralizing core guidelines and separating specialized instructions into dedicated files.
Highlights
- Reorganized AI Agent Instructions: I've introduced a new
.agents/rules/directory to house structured guidelines for AI agents, improving overall maintainability and clarity of instructions. - Centralized Core Guidelines: Core project guidelines, including coding standards, commit message conventions, and PR procedures, have been consolidated into a new
base.mdfile within the.agents/rules/directory. - Dedicated Context-Specific Rules: New, specialized rule files (
browser-extension.mdandwebsite.md) have been created to provide targeted guidelines for specific areas of the codebase, such as browser extension development and website documentation. - Updated Instruction References: Existing AI instruction files (
.cursorrules,.github/instructions/base.instructions.md,CLAUDE.md) have been updated to point to the new, reorganized rule structure, ensuring all agents reference the correct and up-to-date guidelines. - Improved Cross-Referencing: The new rule files include cross-references to related guidelines, facilitating easier navigation and a more comprehensive understanding of the project's standards.
Using Gemini Code Assist
The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.
Invoking Gemini
You can request assistance from Gemini at any point in your pull request via creating an issue comment (i.e. comment on the pull request page) using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands.
| Feature | Command | Description |
|---|---|---|
| Code Review | /gemini review |
Performs a code review for the current pull request in its current state. |
| Pull Request Summary | /gemini summary |
Provides a summary of the current pull request in its current state. |
| Comment | @gemini-code-assist | Responds in comments when explicitly tagged, both in issue comments and review comments. |
| Help | /gemini help |
Displays a list of available commands. |
Customization
To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.
Limitations & Feedback
Gemini Code Assist is currently in preview and may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments to provide feedback.
You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.
Footnotes
-
Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩
Codecov ReportAll modified and coverable lines are covered by tests ✅
Additional details and impacted files@@ Coverage Diff @@
## main #683 +/- ##
=======================================
Coverage 90.36% 90.36%
=======================================
Files 99 99
Lines 5541 5541
Branches 1183 1183
=======================================
Hits 5007 5007
Misses 534 534 ☔ View full report in Codecov by Sentry. 🚀 New features to boost your workflow:
|
Deploying repomix with
|
| Latest commit: |
7ae7aac
|
| Status: | ✅ Deploy successful! |
| Preview URL: | https://4e4d3d55.repomix.pages.dev |
| Branch Preview URL: | https://feat-agent-rules-organizatio.repomix.pages.dev |
There was a problem hiding this comment.
Pull Request Overview
Reorganize and centralize AI agent instructions by moving legacy guidelines into dedicated .agents/rules/ files and replacing outdated markdown with pointers to the new structure.
- Remove old instruction files (
CLAUDE.md, GitHub release note guidelines, base instructions). - Introduce new rule files under
.agents/rules/and update references. - Simplify pointer files (
.cursorrules, rootCLAUDE.md) to reference the new rule directory.
Reviewed Changes
Copilot reviewed 8 out of 8 changed files in this pull request and generated 4 comments.
Show a summary per file
| File | Description |
|---|---|
| website/CLAUDE.md | Deleted obsolete website documentation; replaced with centralized rule references. |
| CLAUDE.md | Stripped detailed AI instructions; added pointer to .agents/rules/base.md. |
| .github/instructions/github-release-note.instructions.md | Removed legacy GitHub release note guidelines; consolidated in base rules. |
| .github/instructions/base.instructions.md | Removed detailed instructions; left only pointer to new base rule file. |
| .cursorrules | Replaced previous context with pointer to .agents/rules/base.md. |
| .agents/rules/website.md | Added description field but missing applyTo in frontmatter. |
| .agents/rules/browser-extension.md | New browser extension guidelines file; frontmatter lacks applyTo property. |
| .agents/rules/base.md | Added core project guidelines; frontmatter missing applyTo directive. |
There was a problem hiding this comment.
Code Review
The pull request reorganizes AI agent instructions, improving maintainability and context-specific application by creating dedicated rule files. The changes involve moving project guidelines and consolidating information into new .agents/rules/ files, with updates to reference the new structure. I've provided feedback on ensuring accuracy of file paths and verifying the impact of abstracting detailed instructions.
![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 (4)
.agents/rules/base.md (2)
75-75: Add missing period.
A period is needed at the end of this sentence to maintain consistency in the commit message guideline examples.
116-116: Fix grammar in output directive.
Consider rephrasing for clarity, e.g.:
“Include all content without being abbreviated, unless specified otherwise.”.github/instructions/base.instructions.md (1)
1-6: Optional: Align front matter with new rule file conventions.
To maintain consistency across documentation, you may replace theapplyTofield with adescriptionentry in the YAML front matter:- --- - applyTo: '**' - --- + --- + description: Legacy instructions streamlined; please refer to the centralized rules in .agents/rules/base.md. + ---CLAUDE.md (1)
5-5: Use a clickable Markdown link for the file pathConverting the file path into a Markdown link improves navigation in rendered documentation.
- Please make sure to check the rules written in `.agents/rules/base.md` as they contain important project-specific guidelines and instructions. + Please make sure to check the rules written in [.agents/rules/base.md](.agents/rules/base.md) as they contain important project-specific guidelines and instructions.
📜 Review details
Configuration used: .coderabbit.yaml
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (8)
.agents/rules/base.md(1 hunks).agents/rules/browser-extension.md(1 hunks).agents/rules/website.md(1 hunks).cursorrules(1 hunks).github/instructions/base.instructions.md(1 hunks).github/instructions/github-release-note.instructions.md(0 hunks)CLAUDE.md(1 hunks)website/CLAUDE.md(0 hunks)
💤 Files with no reviewable changes (2)
- website/CLAUDE.md
- .github/instructions/github-release-note.instructions.md
🧰 Additional context used
🪛 LanguageTool
.agents/rules/browser-extension.md
[uncategorized] ~46-~46: The preposition ‘to’ seems more likely in this position.
Context: ...dding New Languages 1. Create directory in app/_locales/[language_code]/ 2. Add ...
(AI_HYDRA_LEO_REPLACE_IN_TO)
.agents/rules/base.md
[uncategorized] ~75-~75: A period might be missing here.
Context: ...- Description must start with a capital letter ## Pull Request Guidelines - All pull ...
(AI_EN_LECTOR_MISSING_PUNCTUATION_PERIOD)
[uncategorized] ~116-~116: Possible missing preposition found.
Context: ...ble ## Generate Comprehensive Output - Include all content without abbreviation, unles...
(AI_HYDRA_LEO_MISSING_TO)
⏰ Context from checks skipped due to timeout of 90000ms (19)
- GitHub Check: Test (macos-latest, 22.x)
- GitHub Check: Test (windows-latest, 21.x)
- GitHub Check: Test (windows-latest, 23.x)
- GitHub Check: Test (windows-latest, 20.x)
- GitHub Check: Test (windows-latest, 18.0.0)
- GitHub Check: Test (ubuntu-latest, 18.x)
- GitHub Check: Test (ubuntu-latest, 21.x)
- GitHub Check: Test (ubuntu-latest, 20.x)
- GitHub Check: Build and run (macos-latest, 20.x)
- GitHub Check: Build and run (macos-latest, 21.x)
- GitHub Check: Build and run (macos-latest, 22.x)
- GitHub Check: Build and run (windows-latest, 21.x)
- GitHub Check: Build and run (ubuntu-latest, 23.x)
- GitHub Check: Build and run (ubuntu-latest, 19.x)
- GitHub Check: Build and run (ubuntu-latest, 24.x)
- GitHub Check: Build and run (ubuntu-latest, 21.x)
- GitHub Check: auto-review
- GitHub Check: Analyze (javascript-typescript)
- GitHub Check: Cloudflare Pages
🔇 Additional comments (5)
.agents/rules/base.md (1)
1-137: Consolidated project guidelines are clear and well-structured.
The newbase.mdeffectively centralizes coding standards, commit conventions, PR workflows, testing guidance, and release note instructions into a single source of truth..agents/rules/website.md (1)
1-44: Specialized website guidelines are concise and comprehensive.
The updated description front matter clearly scopes these rules to the documentation site, and the steps for navigation and language support are well laid out..agents/rules/browser-extension.md (1)
1-50: Browser extension rules are well-documented and complete.
The manifest, directory structure, development commands, and i18n steps are clearly defined, providing all needed context for extension work..cursorrules (1)
1-2: Pointer to centralized rules is accurate.
The single-line pointer correctly directs contributors to the new.agents/rules/base.mdfor full guidelines.CLAUDE.md (1)
5-5: Approved redirect to centralized rulesThis succinctly directs readers to the new
.agents/rules/base.mdand aligns with the project-wide consolidation of guidelines.
Summary
.agents/rules/directory with clear descriptionsChanges
CLAUDE.mdto.agents/rules/base.mdbrowser-extension.mdrule file for browser development guidelinesbase.mdThis improves organization by separating core project rules from extension-specific and website-specific guidelines, making it easier for AI agents to apply the appropriate rules based on context.
Checklist
npm run testnpm run lint🤖 Generated with Claude Code