YPE-1006: Update AGENTS.md & CLAUDE.md files so that AI agents can better work with this repo #90
Conversation
|
|
Codex usage limits have been reached for code reviews. Please check with the admins of this repo to increase the limits by adding credits. |
Greptile SummaryThis PR restructures AI agent documentation to improve how AI coding assistants interact with the repository.
The documentation accurately describes the monorepo structure, build tools, and development workflow. Minor count discrepancies exist in test file and component counts. Confidence Score: 5/5
Important Files Changed
Sequence DiagramsequenceDiagram
participant Dev as Developer
participant AI as AI Agent
participant Root as AGENTS.md (root)
participant Pkg as Package AGENTS.md
participant Guide as review-guidelines.md
participant Greptile as greptile.json
Dev->>AI: Request code assistance
AI->>Root: Read monorepo overview
Root-->>AI: Structure, patterns, commands, anti-patterns
AI->>Pkg: Read package-specific docs
Pkg-->>AI: Package structure, API, conventions
Dev->>AI: Request code review
AI->>Greptile: Load review configuration
Greptile-->>AI: Comment types, rules, file references
AI->>Guide: Load review checklist
Guide-->>AI: Security, performance, accessibility checks
AI-->>Dev: Provide targeted review feedback
|
|
Hey @bmanquen , this PR is ready for review. I'll create a ticket in JIRA so that this does get tracked. This is very important for us as we create and if we use AI tools to create on this repo, this makes things easier. And I hope that it helps your development workflow as well |
|
@greptileai, I've made some changes. Let me know if this is good to you. Also, I want to hear what you think about the greptile.json file. |
cameronapak
changed the title
![greptile-apps[bot]](https://avatars.githubusercontent.com/in/867647?s=60&v=4){kind=small}
There was a problem hiding this comment.
Looking at your changes, I think this is a significant improvement for AI agents working with this repo. Here's my assessment:
What Works Really Well
AGENTS.md transformation: The move from verbose documentation to concise, actionable reference is excellent. The new format with:
- Clear structure overview
- Key patterns and anti-patterns
- Critical gotchas section
- Command reference
This is much more useful for AI agents than the previous wall of text.
Separation of concerns: Moving the detailed review guidelines to docs/review-guidelines.md keeps the main AGENTS.md focused while preserving the comprehensive checklist.
Package-specific AGENTS.md files: These provide focused context for each package, which is perfect for when AI agents are working on specific parts of the monorepo.
The greptile.json File - This is Clever
I really like what you've done here. The greptile.json configuration is smart because it:
- Enforces architectural patterns - The dependency order rule (core → hooks → ui) is critical for this monorepo
- Captures React patterns - The forwardRef requirement is a good UI consistency rule
- Prevents common mistakes - The workspace protocol rule will save headaches
- References comprehensive guidelines - Pointing to
docs/review-guidelines.mdgives AI the full context when needed
The rules are specific and actionable, which is exactly what AI agents need.
Minor Suggestions
-
In the main
AGENTS.md, you might add a note about the minimum Node.js version requirement (20.0.0+) -
Consider adding a rule in
greptile.jsonabout the unified versioning pattern since that's such a critical aspect of this monorepo
Overall, this is a thoughtful approach that balances conciseness with completeness. AI agents should be much more effective with these changes. The greptile.json file in particular shows you're thinking strategically about how to guide AI behavior through tooling configuration.
bmanquen
left a comment
bmanquen
left a comment
There was a problem hiding this comment.
Great work just some comments that will hopefully help improve a couple areas.
Updated the wording to say "many" versus having very specific numbers that would have to be updated on every PR. This simplifies it so that AI gets the information it needs and we don't have to update this.
Improve descriptions in AGENTS.md files for core, hooks, and ui packages. This clarifies the purpose of each package and its key features.
Add specific examples of data fetching hooks to the AGENTS.md file for the hooks package.
Replace `vitest run --project storybook` with `pnpm test:integration` for consistency across the project. Also add a note about tagging integration tests for better organization.
cameronapak
force-pushed
the
agents-md
branch
from
46e1431 to
398ae79
Compare
|
Gentle bump requesting review on this. @davidfedor @bmanquen background: The context of where I'm coming from is I find that this is incredibly important as I do work, as others do work with AI, and I use AI in my everyday workflow as I'm creating and riffing and digging deeper into code. And so this would mean a lot to have something like this merged in. |
Add "Related packages" sections to each package's AGENTS.md to help AI agents navigate between packages and understand when to use each. Addresses PR review feedback requesting cross-linking documentation.
Hooks delegate HTTP requests to core, so tests use Vitest mock factories rather than MSW for network interception.
Add code examples showing basic usage patterns for: - BibleTextView - VerseOfTheDay - BibleReader (compound component) - BibleChapterPicker (controlled component) - BibleVersionPicker (controlled component) - BibleWidgetView - YouVersionAuthButton Addresses PR review feedback requesting example code for top components.
Add guidance to prefer Storybook with play functions for UI component testing, addressing review feedback.
Addresses PR review feedback requesting more thorough examples so AI agents can understand hook naming conventions and usage patterns.
Remove unnecessary wrapper divs from usage examples since each component already includes the data-yv-sdk attribute on its root element. Also fix BibleTextView example to include required versionId prop.
Add exclude patterns for *.test.ts, *.test.tsx, *.stories.ts, and *.stories.tsx to prevent type declaration generation for test files.
Because people, including myself, will be using AI agents to interact with and to create and work with this repository, I wanted to make sure that AI has the right guidance that it needs so that when it produces code, it produces code in line with the desires and the standards that we have set forth.
This is the second attempt to make the agent's files better so that AI can be a better assistant and helper as we create and do what God's called us to do
Important
This does not include a changeset because it doesn't change any features that an end-user interacts with.
One important piece of information is that the AGENTS.md file is compatible with a ton of AI agents such as people who use OpenCode or if they use Aider or if they use Kilo code or Cursor. However, AGENTS.md is not. They are all incompatible with Claude, which is why I do a symlink and create a CLAUDE.md file for each of the agent files that just points directly to the AGENTS.md file.
https://agents.md sets the tone for overarching idea and simple application of how AGENTS.md works.
Jira ticket: https://lifechurch.atlassian.net/browse/YPE-1006