Skip to content

Commit ddf651f

Browse files
CopilotiMacTia
Copilot
and
iMacTia
committed
Add AI agent guidelines for Claude, Cursor, and Copilot
Co-authored-by: iMacTia <2527520+iMacTia@users.noreply.github.com>
1 parent 2d6a5f3 commit ddf651f

3 files changed

Lines changed: 251 additions & 0 deletions

File tree

‎.claude/CLAUDE.md‎

Lines changed: 46 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,46 @@
1+
# Claude AI Agent Instructions for Faraday
2+
3+
## Overview
4+
You are working on the **Faraday** repository, a Ruby HTTP client library with a middleware-based architecture. Before making any code changes or suggestions, you **must** read and follow the comprehensive guidelines in `.ai/guidelines.md`.
5+
6+
## Primary Directive
7+
**Always reference `.ai/guidelines.md`** for:
8+
- Code style and structure conventions
9+
- Middleware implementation patterns
10+
- Adapter development guidelines
11+
- Testing requirements with RSpec
12+
- Documentation standards (YARD)
13+
- Contribution workflow
14+
15+
## Self-Maintaining Responsibility
16+
As a Claude AI agent, you are responsible for:
17+
1. **Reading** `.ai/guidelines.md` before every contribution
18+
2. **Following** all Faraday-specific conventions outlined there
19+
3. **Proposing updates** to `.ai/guidelines.md` when you identify:
20+
- New code patterns not yet documented
21+
- Changes to existing conventions
22+
- Improved practices that should become standard
23+
- Inconsistencies between the guidelines and actual codebase
24+
25+
## Key Faraday Concepts
26+
- **Middleware Architecture**: All middleware inherit from `Faraday::Middleware` and use hooks (`on_request`, `on_complete`, `on_error`)
27+
- **Adapter Pattern**: Adapters extend `Faraday::MiddlewareRegistry` and implement `call`, `build_connection`, etc.
28+
- **Registry System**: Both middleware and adapters register themselves with unique keys
29+
- **Testing**: Use RSpec with shared examples, stubs instead of real network calls
30+
- **Documentation**: YARD comments for all public APIs
31+
32+
## What NOT to Do
33+
- Do not provide generic Ruby or RSpec advice—focus on Faraday-specific patterns
34+
- Do not suggest changes that violate established conventions without first proposing guideline updates
35+
- Do not implement middleware or adapters without checking existing patterns in the codebase
36+
37+
## Quick Reference
38+
- Main guidelines: `.ai/guidelines.md`
39+
- Contributing guide: `.github/CONTRIBUTING.md`
40+
- Example middleware: `lib/faraday/request/json.rb`
41+
- Example adapter: `lib/faraday/adapter/test.rb`
42+
- Middleware base: `lib/faraday/middleware.rb`
43+
44+
---
45+
46+
**Remember**: Keep `.ai/guidelines.md` current. If you notice any drift between documentation and reality, propose updates to maintain accuracy.

‎.cursorrules‎

Lines changed: 84 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,84 @@
1+
# Cursor AI Rules for Faraday Repository
2+
3+
## Primary Guidelines Reference
4+
**CRITICAL**: Before making any code changes, read `.ai/guidelines.md` for comprehensive Faraday-specific conventions.
5+
6+
## About Faraday
7+
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.
8+
9+
## Core Responsibilities
10+
1. **Read First**: Always consult `.ai/guidelines.md` before contributing
11+
2. **Follow Conventions**: Adhere to all Faraday-specific patterns documented in guidelines
12+
3. **Maintain Guidelines**: Propose updates to `.ai/guidelines.md` when:
13+
- You identify undocumented patterns in the codebase
14+
- Existing conventions change
15+
- Better practices emerge
16+
17+
## Faraday-Specific Patterns
18+
19+
### Middleware (See `.ai/guidelines.md` for details)
20+
- Inherit from `Faraday::Middleware`
21+
- Use `DEFAULT_OPTIONS` constant
22+
- Implement only needed hooks: `on_request`, `on_complete`, `on_error`
23+
- Register via `Faraday::Middleware.register_middleware`
24+
- Keep stateless; use `env` hash for state
25+
26+
### Adapters (See `.ai/guidelines.md` for details)
27+
- Extend `Faraday::MiddlewareRegistry`
28+
- Implement `call`, `build_connection`, `close`
29+
- Place in `lib/faraday/adapter/`
30+
- Register via `Faraday::Adapter.register_middleware`
31+
- Support parallel requests if possible
32+
33+
### Testing with RSpec
34+
- Use shared examples for adapters/middleware
35+
- Mock network calls; never make real HTTP requests
36+
- Test organization mirrors `lib/` structure
37+
- See `spec/support` for test helpers
38+
39+
### Documentation
40+
- YARD-style comments for all public APIs
41+
- Update docs/ for user-facing features
42+
- Keep README and CHANGELOG current
43+
44+
## Code Organization
45+
```
46+
lib/faraday/
47+
├── adapter/ # HTTP adapters
48+
├── request/ # Request middleware
49+
├── response/ # Response middleware
50+
└── middleware.rb # Base middleware class
51+
52+
spec/faraday/
53+
└── (mirrors lib structure)
54+
```
55+
56+
## Quick Start Examples
57+
58+
**Middleware Registration**:
59+
```ruby
60+
Faraday::Request.register_middleware(my_middleware: MyMiddleware)
61+
```
62+
63+
**Adapter Registration**:
64+
```ruby
65+
Faraday::Adapter.register_middleware(my_adapter: MyAdapter)
66+
```
67+
68+
## Contribution Workflow
69+
- Follow `.github/CONTRIBUTING.md`
70+
- Run tests: `bundle exec rspec`
71+
- Check style: `bundle exec rubocop`
72+
- Use inclusive language
73+
74+
## Self-Maintaining Principle
75+
This file and `.ai/guidelines.md` must stay current with the codebase. When you detect any divergence between documentation and implementation, propose updates to keep them aligned.
76+
77+
---
78+
79+
**Key Files**:
80+
- `.ai/guidelines.md` - Complete conventions (READ THIS FIRST)
81+
- `.github/CONTRIBUTING.md` - Contribution process
82+
- `lib/faraday/middleware.rb` - Middleware base class
83+
- Example: `lib/faraday/request/json.rb` (middleware)
84+
- Example: `lib/faraday/adapter/test.rb` (adapter)

‎.github/copilot-instructions.md‎

Lines changed: 121 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,121 @@
1+
# GitHub Copilot Instructions for Faraday
2+
3+
## Essential Reading
4+
**Before making any code suggestions**, consult `.ai/guidelines.md` for comprehensive Faraday-specific conventions and patterns.
5+
6+
## About This Repository
7+
Faraday is a Ruby HTTP client library that provides:
8+
- A middleware-based architecture (similar to Rack)
9+
- A common interface over various HTTP adapters (Net::HTTP, HTTPClient, etc.)
10+
- Extensible request/response processing pipeline
11+
12+
## Your Responsibilities
13+
As GitHub Copilot working on Faraday, you must:
14+
15+
1. **Read & Follow**: Always reference `.ai/guidelines.md` for Faraday conventions
16+
2. **Stay Current**: Suggest updates to `.ai/guidelines.md` when you notice:
17+
- New patterns not yet documented
18+
- Changes to existing conventions
19+
- Discrepancies between guidelines and actual code
20+
3. **Focus on Faraday**: Provide Faraday-specific guidance, not generic Ruby/RSpec tips
21+
22+
## Core Architecture Patterns
23+
24+
### Middleware System
25+
All middleware must:
26+
- Inherit from `Faraday::Middleware`
27+
- Define `DEFAULT_OPTIONS` constant if configurable
28+
- Implement only required hooks: `on_request`, `on_complete`, or `on_error`
29+
- Register with a unique key via `Faraday::Middleware.register_middleware`
30+
- Remain stateless (store state in `env` hash only)
31+
32+
Example structure:
33+
```ruby
34+
module Faraday
35+
class Request
36+
class MyMiddleware < Middleware
37+
DEFAULT_OPTIONS = { option: 'value' }.freeze
38+
39+
def on_request(env)
40+
# Modify request
41+
end
42+
end
43+
end
44+
end
45+
46+
Faraday::Request.register_middleware(my_middleware: Faraday::Request::MyMiddleware)
47+
```
48+
49+
### Adapter System
50+
All adapters must:
51+
- Extend `Faraday::MiddlewareRegistry`
52+
- Implement `call(env)` method
53+
- Implement `build_connection(env)` for connection setup
54+
- Implement `close` for cleanup
55+
- Be placed in `lib/faraday/adapter/`
56+
- Register via `Faraday::Adapter.register_middleware`
57+
58+
For parallel support:
59+
- Include `Parallelism` module
60+
- Set `supports_parallel = true`
61+
62+
### Testing Conventions
63+
- Use RSpec for all tests
64+
- Leverage shared examples for adapters and middleware (see `spec/support`)
65+
- Mock HTTP calls; never make real network requests
66+
- Follow test organization: `spec/faraday/` mirrors `lib/faraday/`
67+
- Test middleware: use doubles for `app` and verify hook invocations
68+
69+
### Documentation Standards
70+
- Add YARD comments to all public APIs
71+
- Update `docs/` for user-facing features
72+
- Keep README.md and CHANGELOG.md current
73+
- Document new middleware/adapters in `docs/` folder
74+
75+
## Project Structure
76+
```
77+
lib/faraday/
78+
├── adapter/ # HTTP backend adapters
79+
│ └── test.rb # Test adapter (example)
80+
├── request/ # Request middleware
81+
│ ├── json.rb # JSON encoding (example)
82+
│ └── authorization.rb
83+
├── response/ # Response middleware
84+
├── middleware.rb # Base middleware class
85+
└── adapter.rb # Base adapter class
86+
87+
spec/faraday/
88+
└── (mirrors lib structure)
89+
```
90+
91+
## Code Quality Requirements
92+
- Follow RuboCop style guide (`.rubocop.yml`)
93+
- Ensure all code passes: `bundle exec rubocop`
94+
- All features need tests: `bundle exec rspec`
95+
- Use inclusive language (see `.github/CONTRIBUTING.md`)
96+
97+
## Contribution Process
98+
1. Check `.github/CONTRIBUTING.md` for workflow
99+
2. New features require tests and documentation
100+
3. Adapters/middleware should be separate gems (link from this project)
101+
4. Follow semantic versioning for breaking changes
102+
103+
## Self-Maintaining Guidelines
104+
You are responsible for keeping `.ai/guidelines.md` accurate and current. When you identify:
105+
- Code patterns not reflected in guidelines
106+
- Convention changes
107+
- Better practices
108+
109+
Propose updates to `.ai/guidelines.md` to maintain alignment with the actual codebase.
110+
111+
## Reference Files
112+
- **Complete Guidelines**: `.ai/guidelines.md` (PRIMARY REFERENCE)
113+
- **Contribution Guide**: `.github/CONTRIBUTING.md`
114+
- **Middleware Base**: `lib/faraday/middleware.rb`
115+
- **Middleware Example**: `lib/faraday/request/json.rb`
116+
- **Adapter Example**: `lib/faraday/adapter/test.rb`
117+
- **Style Guide**: `.rubocop.yml`
118+
119+
---
120+
121+
**Remember**: The guidelines in `.ai/guidelines.md` are the source of truth for Faraday conventions. Keep them current and refer to them consistently.

0 commit comments

Comments
 (0)