docs: add AGENTS.md with CLI design patterns for AI agents#3676
Merged
docs: add AGENTS.md with CLI design patterns for AI agents#3676
Conversation
k80bowman
approved these changes
Apr 21, 2026
Contributor
k80bowman
left a comment
k80bowman
left a comment
There was a problem hiding this comment.
Just one question, but it's not blocking. This is awesome, thank you!
Add comprehensive guidelines for AI agents working on the CLI codebase. This file documents CLI design patterns from RFC 000282, including: - Command naming conventions (lowercase-hyphenated, action verbs) - Arguments and flags best practices (prefer flags over args) - Language and help text guidelines - Output and exit code handling - Data handling patterns (thin validation, concurrent API calls) - UX component usage (ux.action, ux.table, confirmCommand, etc.) This helps ensure AI coding assistants like Claude, Copilot, and Cursor follow consistent patterns when contributing to the codebase.
Add component source documentation clarifying that basic UX components (stdout, stderr, action.start/stop) come from oclif/core, while more involved components (table, color system) come from heroku-cli-util. Update component references to use correct prefixes (hux.table, hux.confirm, etc.) and add link to heroku-cli-util color system documentation.
eablack
force-pushed
the
eb/add-agents-md
branch
from
10d0d4b to
132c24f
Compare
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Adds an AGENTS.md file to document CLI design patterns and best practices for AI agents (like Claude, Copilot, Cursor) working on this codebase. The guidelines are derived from RFC 000282: CLI Design Patterns and Best Practices.
Type of Change
Patch Updates (patch semver update)
Testing
Notes:
This is a documentation-only change that adds guidelines for AI agents. No functional code changes.
Steps: