Add comprehensive AI agent guidelines for Claude, Cursor, and GitHub Copilot (#1642)

Co-authored-by: copilot-swe-agent[bot] <[email protected]>
Co-authored-by: iMacTia <[email protected]>

Author: Copilot

.claude/CLAUDE.md

@@ -0,0 +1,30 @@
+# Claude AI Agent Instructions for Faraday
+
+## About Faraday
+Faraday is a Ruby HTTP client library with a middleware-based architecture (similar to Rack). It provides a common interface over various HTTP adapters and uses middleware for request/response processing.
+
+## Primary Directive
+**Before making any code changes or suggestions**, you **must** read and follow the comprehensive guidelines in `.ai/guidelines.md`.
+
+## Your Responsibilities
+1. **Read** `.ai/guidelines.md` for all Faraday-specific conventions and patterns
+2. **Follow** the established conventions documented there
+3. **Propose updates** to `.ai/guidelines.md` when you identify:
+   - New code patterns not yet documented
+   - Changes to existing conventions
+   - Inconsistencies between guidelines and actual codebase
+
+## Important Context
+- **New middleware and adapters** should be created as separate gems, NOT added to the base Faraday repository (with rare exceptions for widely-used core middleware)
+- See [faraday-net_http](https://github.com/lostisland/faraday-net_http) as an example adapter in its own repository
+- Focus on Faraday-specific patterns, not generic Ruby/RSpec advice
+
+## Reference Files
+- **`.ai/guidelines.md`** - Complete Faraday conventions (PRIMARY REFERENCE)
+- `.github/CONTRIBUTING.md` - Contribution process and policies
+- `lib/faraday/middleware.rb` - Middleware base class
+- `lib/faraday/request/json.rb` - Example middleware implementation
+
+---
+
+**Keep `.ai/guidelines.md` current.** Propose updates when you notice any drift between documentation and reality.

.cursorrules

@@ -0,0 +1,29 @@
+# Cursor AI Rules for Faraday Repository
+
+## Primary Guidelines Reference
+**CRITICAL**: Before making any code changes, read `.ai/guidelines.md` for comprehensive Faraday-specific conventions.
+
+## About Faraday
+Faraday is a Ruby HTTP client library with a middleware-based architecture similar to Rack. It provides a common interface over many HTTP adapters and uses middleware for request/response processing.
+
+## Core Responsibilities
+1. **Read** `.ai/guidelines.md` for all implementation details, patterns, and conventions
+2. **Follow** the Faraday-specific patterns documented in the guidelines
+3. **Propose updates** to `.ai/guidelines.md` when conventions change or new patterns emerge
+
+## Important Context
+- **New middleware and adapters** belong in separate repositories and gems, NOT in the base Faraday repo
+  - Only middleware used by the vast majority of projects can be considered for the base repo
+  - See [faraday-net_http](https://github.com/lostisland/faraday-net_http) for an example adapter in its own repository
+- Focus on Faraday-specific patterns, not generic Ruby/RSpec knowledge
+- Run tests with `bundle exec rspec` and check style with `bundle exec rubocop`
+
+## Reference Files
+- **`.ai/guidelines.md`** - Complete conventions and patterns (READ THIS FIRST)
+- `.github/CONTRIBUTING.md` - Contribution process and workflow
+- `lib/faraday/middleware.rb` - Middleware base class
+- `lib/faraday/request/json.rb` - Example middleware
+
+---
+
+**Self-Maintaining**: Keep `.ai/guidelines.md` aligned with the actual codebase. Propose updates when you detect any divergence.

.github/copilot-instructions.md

@@ -0,0 +1,48 @@
+# GitHub Copilot Instructions for Faraday
+
+## Essential Reading
+**Before making any code suggestions**, consult `.ai/guidelines.md` for comprehensive Faraday-specific conventions and patterns.
+
+## About This Repository
+Faraday is a Ruby HTTP client library that provides:
+- A middleware-based architecture (similar to Rack)
+- A common interface over various HTTP adapters (Net::HTTP, HTTPClient, etc.)
+- Extensible request/response processing pipeline
+
+## Your Responsibilities
+As GitHub Copilot working on Faraday, you must:
+
+1. **Read & Follow**: Always reference `.ai/guidelines.md` for all Faraday conventions and implementation details
+2. **Stay Current**: Suggest updates to `.ai/guidelines.md` when you notice:
+   - New patterns not yet documented
+   - Changes to existing conventions
+   - Discrepancies between guidelines and actual code
+3. **Focus on Faraday**: Provide Faraday-specific guidance, not generic Ruby/RSpec tips
+
+## Critical Context
+
+### Middleware and Adapters
+- **New middleware and adapters should be separate gems**, NOT added to the base Faraday repository
+- Only middleware expected to be used by the vast majority of projects can be considered for the base repo
+- See [faraday-net_http](https://github.com/lostisland/faraday-net_http) as an example of an adapter in its own repository
+- Consult `.ai/guidelines.md` for detailed implementation patterns
+
+### Code Quality
+- Follow RuboCop style guide (`.rubocop.yml`)
+- Run tests: `bundle exec rspec`
+- Check style: `bundle exec rubocop`
+- Use inclusive language (see `.github/CONTRIBUTING.md`)
+
+## Self-Maintaining Guidelines
+Keep `.ai/guidelines.md` accurate and current. When you identify code patterns not reflected in guidelines, convention changes, or better practices, propose updates to maintain alignment with the actual codebase.
+
+## Reference Files
+- **`.ai/guidelines.md`** - Complete conventions and patterns (PRIMARY REFERENCE)
+- `.github/CONTRIBUTING.md` - Contribution process and workflow
+- `lib/faraday/middleware.rb` - Middleware base class
+- `lib/faraday/request/json.rb` - Example middleware implementation
+- `.rubocop.yml` - Code style guide
+
+---
+
+**Remember**: The guidelines in `.ai/guidelines.md` are the source of truth for Faraday conventions. Keep them current and refer to them consistently.