Skip to content

Conversation

atesgoral
Copy link
Contributor

@atesgoral atesgoral commented Sep 14, 2025

Summary

This PR introduces AGENTS.md, following the new agents.md standard for providing AI coding assistant guidance. This replaces the previous Claude-specific documentation with a universal format supported by 20+ AI coding tools.

Changes Made

  • Added comprehensive AGENTS.md with structured guidance for AI coding assistants including:

    • Project overview and environment setup
    • Build and test commands
    • Code style guidelines and commit conventions
    • Release process documentation
    • Architecture overview with core components
    • Integration patterns and best practices
  • Adopted agents.md standard format for better compatibility with AI coding tools like:

    • GitHub Copilot
    • Cursor
    • OpenAI Codex
    • VS Code AI extensions
    • And 15+ other tools
  • Consolidated tool-specific rules by migrating Cursor-specific release changelog guidelines into the universal AGENTS.md format and removing .cursor/rules/release-changelogs.mdc

Benefits

  1. Universal compatibility: Works with any AI coding assistant that supports the agents.md standard
  2. Comprehensive guidance: Covers development workflow, architecture, testing, and release processes
  3. Improved developer experience: AI assistants can better understand project structure and conventions
  4. Future-proof: Follows emerging industry standard for AI coding assistant configuration

Technical Details

The AGENTS.md includes essential information for productive development:

  • Commands for building, testing, and linting
  • Architecture documentation for MCP::Server, MCP::Client, and transport layers
  • Three component definition patterns (class inheritance, define methods, server registration)
  • Schema validation and context passing patterns
  • Integration patterns for Rails, CLI, and HTTP services

This change enhances the developer experience for anyone working with AI coding assistants on this repository while maintaining all essential technical guidance.

Types of changes

  • Bug fix (non-breaking change which fixes an issue)
  • New feature (non-breaking change which adds functionality)
  • Breaking change (fix or feature that would cause existing functionality to change)
  • Documentation update

Checklist

  • I have read the MCP Documentation
  • My code follows the repository's style guidelines
  • New and existing tests pass locally
  • I have added appropriate error handling
  • I have added or updated documentation as needed

Additional context

PR generated with the help of Claude Code

atesgoral and others added 4 commits September 14, 2025 11:43
🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <noreply@anthropic.com>
…ndard

- Adopt the new agents.md format for AI coding assistant guidance
- Reorganize content into standard sections: project overview, dev setup, build commands, testing, code style, and architecture
- Maintain all essential technical information while improving accessibility
- Support the growing ecosystem of AI tools that recognize agents.md

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <noreply@anthropic.com>
…ific files

- Add release process section to AGENTS.md with changelog guidelines
- Include Keep a Changelog format requirements and entry formatting rules
- Remove .cursor/rules/release-changelogs.mdc to favor universal AGENTS.md format
- Ensure all AI coding assistants have access to release documentation guidelines

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <noreply@anthropic.com>
Co-authored-by: Koichi ITO <koic.ito@gmail.com>
Copy link
Member

@koic koic left a comment

Choose a reason for hiding this comment

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

I think commits could be squashed, but I’ll leave it to you. Thank you!

@atesgoral atesgoral merged commit aba6163 into main Sep 23, 2025
13 checks passed
@atesgoral atesgoral deleted the ag/agents-doc branch September 23, 2025 03:25
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

2 participants