1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
|
# Faraday-Specific AI Agent Guidelines
## Purpose
These guidelines ensure all AI agents (Copilot, Claude, Cursor, etc.) contribute code that is consistent with the conventions and patterns used in the Faraday codebase. Agents must:
- Read these guidelines before any work.
- Suggest updates whenever conventions change or new patterns emerge, keeping this document up to date.
## Code Style & Structure
- **Do not include basic Ruby or RSpec tips**—assume agents know the language, RuboCop, and test basics.
- Use the established Faraday directory structure (`lib/faraday/` for main code, `spec/faraday/` for tests).
- Classes and files must use descriptive, conventional Ruby names (e.g., `Faraday::MyAdapter` in `lib/faraday/my_adapter.rb`).
## Middleware Implementation
- All middleware must inherit from `Faraday::Middleware`.
- Use a `DEFAULT_OPTIONS` constant for configuration defaults. Validate options via `validate_default_options` if needed.
- Middleware should implement any of: `on_request`, `on_complete`, and `on_error` as needed. Only add hooks required for your logic.
- Register middleware via `Faraday::Middleware.register_middleware your_key: YourClass`. Use clear, unique keys.
- Prefer stateless middleware. Store state only in the `env` hash or local variables.
## Adapter Patterns
- Adapters must extend `Faraday::MiddlewareRegistry` and register themselves.
- If providing parallel support, include the `Parallelism` module and set `supports_parallel = true`.
- Implement required methods (`build_connection`, `close`, etc.) as seen in existing adapters.
- Keep each adapter in its own file under `lib/faraday/adapter/`.
## Testing
- All code must be tested with RSpec. Use shared examples for adapters/middleware where applicable (see `spec/support`).
- When testing middleware, use doubles for `app` and verify correct invocation of hooks.
- Use HTTP test helpers and stubs, not real network calls.
- Follow the project's test organization and naming conventions.
## Documentation
- All new public APIs must be documented with YARD-style comments.
- Update README, changelog, or docs/ as needed for significant features or user-facing changes.
- Document any new middleware or adapter in the docs folder if it is a user-facing extension.
## Contribution Workflow
- Follow branch naming and PR guidelines from CONTRIBUTING.md.
- All new features and bugfixes must include relevant tests and documentation.
- Ensure inclusive language.
---
## Self-Maintaining Guidelines
AI agents are responsible for:
- Reading these guidelines before suggesting or making changes.
- Updating this document whenever code conventions change.
- Proposing improvements if they identify code patterns not reflected here.
---
*Keep this file current and aligned with the real conventions and architecture of the Faraday codebase.*
|
