Skip to content

Create AGENTS.md #2561

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom
Draft
wants to merge 4 commits into
base: canary
Choose a base branch
from
Draft

Create AGENTS.md #2561

wants to merge 4 commits into from

Conversation

bookernath
Copy link
Contributor

What/Why?

Add an AGENTS.md file to help AI-assisted development tools in understand the structure of Catalyst as well as the best practices for extending it.

Testing

TBD - need to test various development scenarios

Migration

N/A

@changeset-bot changeset-bot
Copy link

changeset-bot bot commented Aug 27, 2025 •
edited
Loading

⚠️ No Changeset found

Latest commit: e7a6fc4

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

@vercel Vercel
Copy link

vercel bot commented Aug 27, 2025 •
edited
Loading

The latest updates on your projects. Learn more about Vercel for GitHub.

Project Deployment Preview Comments Updated (UTC)
catalyst-b2b Ready Ready Preview Comment Sep 4, 2025 4:06am
catalyst-canary Ready Ready Preview Comment Sep 4, 2025 4:06am
3 Skipped Deployments
Project Deployment Preview Comments Updated (UTC)
catalyst Ignored Ignored Sep 4, 2025 4:06am
catalyst-au Ignored Ignored Sep 4, 2025 4:06am
catalyst-uk Ignored Ignored Sep 4, 2025 4:06am

@bookernath bookernath requested a review from Copilot August 27, 2025 15:24
Copilot
Copilot AI reviewed Aug 27, 2025
View reviewed changes
Copy link

@Copilot Copilot AI left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull Request Overview

This PR adds an AGENTS.md file to document the BigCommerce Catalyst codebase architecture for AI-assisted development tools. The documentation explains the custom middleware-based routing system that overrides Next.js defaults, data fetching patterns using Partial Prerendering (PPR), and the separated UI design system.

  • Added comprehensive documentation for the custom routing middleware that resolves URLs via GraphQL instead of file-based routing
  • Documented data fetching patterns including the Streamable utility and PPR configuration
  • Outlined the UI design system architecture with clear separation between business logic and presentation components

Tip: Customize your code reviews with copilot-instructions.md. Create the file or learn how to get started.

core/AGENTS.md Outdated

1. **Queries the BigCommerce GraphQL API** to resolve incoming URL paths to specific entity types (products, categories, brands, blog posts, pages)

2. **Rewrites requests** to internal Next.js routes based on the resolved entity type
Copy link
Preview

Copilot AI Aug 27, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This line ends without proper punctuation. Consider adding a period for consistency with the formatting of other numbered points.

Suggested change
2. **Rewrites requests** to internal Next.js routes based on the resolved entity type
2. **Rewrites requests** to internal Next.js routes based on the resolved entity type.

Copilot uses AI. Check for mistakes.

core/AGENTS.md Outdated

2. **Rewrites requests** to internal Next.js routes based on the resolved entity type

3. **Handles redirects** automatically based on BigCommerce's redirect configuration
Copy link
Preview

Copilot AI Aug 27, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This line ends without proper punctuation. Consider adding a period for consistency with the formatting of other numbered points.

Suggested change
3. **Handles redirects** automatically based on BigCommerce's redirect configuration
3. **Handles redirects** automatically based on BigCommerce's redirect configuration.

Copilot uses AI. Check for mistakes.

@bookernath @Copilot
Create AGENTS.md
bc9e3f0 
Co-Authored-By: Copilot <[email protected]>
matthewvolk
matthewvolk approved these changes Aug 29, 2025
View reviewed changes
Copy link
Contributor

@matthewvolk matthewvolk left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm cool with merging so we can all collaborate and add to it, IMO it's already very valuable so far

core/AGENTS.md

1. **Use React's `cache()` function** for server-side data fetching to ensure deduplication.

2. **Implement proper cache strategies** based on whether user authentication is present.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🍹 Do examples help here?

bookernath and others added 2 commits September 3, 2025 22:38
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Reviewers

Copilot code review Copilot Copilot left review comments

@matthewvolk matthewvolk matthewvolk approved these changes

Assignees
No one assigned
Labels
None yet
Projects
None yet
Milestone
No milestone
Development

Successfully merging this pull request may close these issues.
2 participants
@bookernath @matthewvolk