rails-ai-bridge 5.3.0 → 5.4.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- checksums.yaml +4 -4
- data/.reek.yml +1 -0
- data/CHANGELOG.md +58 -0
- data/README.md +14 -16
- data/SECURITY.md +3 -0
- data/UPGRADING.md +15 -0
- data/docs/BEST_PRACTICES.md +7 -10
- data/docs/EXAMPLES.md +3 -6
- data/docs/GUIDE.md +79 -24
- data/docs/devin-setup.md +5 -8
- data/docs/mcp-security.md +20 -1
- data/docs/ruby-version-support.md +58 -0
- data/lib/generators/rails_ai_bridge/install/command_help.rb +3 -3
- data/lib/generators/rails_ai_bridge/install/install_generator.rb +2 -2
- data/lib/rails_ai_bridge/config/output.rb +6 -0
- data/lib/rails_ai_bridge/configuration.rb +1 -0
- data/lib/rails_ai_bridge/instrumentation.rb +7 -2
- data/lib/rails_ai_bridge/introspectors/config_introspector.rb +21 -5
- data/lib/rails_ai_bridge/introspectors/timezone_introspector.rb +44 -0
- data/lib/rails_ai_bridge/mcp/http_rate_limiter.rb +24 -9
- data/lib/rails_ai_bridge/serializers/README.md +0 -1
- data/lib/rails_ai_bridge/serializers/context_file_serializer.rb +6 -0
- data/lib/rails_ai_bridge/serializers/legacy_agent_files.rb +60 -0
- data/lib/rails_ai_bridge/serializers/providers/codex_serializer.rb +0 -1
- data/lib/rails_ai_bridge/tasks/rails_ai_bridge.rake +5 -5
- data/lib/rails_ai_bridge/tool_result_cache.rb +24 -4
- data/lib/rails_ai_bridge/tools/query/payload_formatter.rb +9 -9
- data/lib/rails_ai_bridge/tools/query.rb +25 -10
- data/lib/rails_ai_bridge/tools/search_code/ruby_search.rb +1 -1
- data/lib/rails_ai_bridge/tools/search_code/validator.rb +20 -1
- data/lib/rails_ai_bridge/version.rb +1 -1
- data/lib/rails_ai_bridge.rb +1 -1
- data/server.json +1 -1
- metadata +4 -1
checksums.yaml
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
---
|
|
2
2
|
SHA256:
|
|
3
|
-
metadata.gz:
|
|
4
|
-
data.tar.gz:
|
|
3
|
+
metadata.gz: 0f4066d47a05fac81d54e926520b483bc043b73f29fb7a2ec118caf133e01559
|
|
4
|
+
data.tar.gz: 9bf88dda78fba7d798008dae187d89f34724ceb64b18e962f27eea0d7cfd3b74
|
|
5
5
|
SHA512:
|
|
6
|
-
metadata.gz:
|
|
7
|
-
data.tar.gz:
|
|
6
|
+
metadata.gz: 36183d3adfadb44f8752bfdf75b499128f98796c4c726c5b615dd49300cac3c4c109b76066810f319712dab6130dc9dd5a06f2405511559d12f3256b09a08a33
|
|
7
|
+
data.tar.gz: 27f36fe2f926077a470f3e49631d3e0eac13bd77e0c788a9a828641f9314255af80a1fe104c02b78eb2e2dbfca1314233daf2173a046a7b52682aecc9fa1e755
|
data/.reek.yml
CHANGED
|
@@ -49,6 +49,7 @@ detectors:
|
|
|
49
49
|
- RailsAiBridge::Config::Output#codex_compact_model_list_limit
|
|
50
50
|
- RailsAiBridge::Config::Output#context_mode
|
|
51
51
|
- RailsAiBridge::Config::Output#copilot_compact_model_list_limit
|
|
52
|
+
- RailsAiBridge::Config::Output#legacy_agent_files
|
|
52
53
|
- RailsAiBridge::Config::Output#managed_region
|
|
53
54
|
- RailsAiBridge::Config::Output#max_tool_response_chars
|
|
54
55
|
- RailsAiBridge::Config::Output#output_dir
|
data/CHANGELOG.md
CHANGED
|
@@ -7,6 +7,64 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
|
|
|
7
7
|
|
|
8
8
|
## [Unreleased]
|
|
9
9
|
|
|
10
|
+
## [5.4.0] - 2026-10-23
|
|
11
|
+
|
|
12
|
+
### Added
|
|
13
|
+
|
|
14
|
+
- `rails_ai_bridge.tool.call` notifications now include `success` and
|
|
15
|
+
`error_class`, while preserving the existing duration, tool name, and
|
|
16
|
+
arguments payload (#339).
|
|
17
|
+
- Ruby version support policy in `docs/ruby-version-support.md` (ticket #341).
|
|
18
|
+
- README Requirements and Ruby policy distinguish blocking Ruby 3.2–3.4 coverage
|
|
19
|
+
from the existing non-blocking Ruby 4.0 / Rails 8.1 canary. The historical Ruby
|
|
20
|
+
3.5 preview is excluded from the matrix.
|
|
21
|
+
- `RailsAiBridge::Introspectors::TimezoneIntrospector` adds runtime confirmation
|
|
22
|
+
metadata to the existing config section (part of #342). `timezone_confirmed`
|
|
23
|
+
compares the IANA identifiers of `config.time_zone` and the current thread's
|
|
24
|
+
`Time.zone`, supporting both Rails names and IANA identifiers. It is false
|
|
25
|
+
when the runtime zone is unavailable or different. Static config introspection
|
|
26
|
+
remains unavailable; tool and serializer rendering is unchanged.
|
|
27
|
+
|
|
28
|
+
### Changed
|
|
29
|
+
|
|
30
|
+
- `rails_query` enforces its row limit in SQL and fetches one sentinel row
|
|
31
|
+
before ActiveRecord materializes results. Summary responses now report the
|
|
32
|
+
same bounded `row_count` and `truncated` semantics as other detail levels
|
|
33
|
+
(#350).
|
|
34
|
+
|
|
35
|
+
### Fixed
|
|
36
|
+
|
|
37
|
+
- Disable the review CLI's background auto-updater in CI so the pinned executable
|
|
38
|
+
cannot be replaced during an automated review.
|
|
39
|
+
- Bound the in-process tool response cache to 1,000 entries and the HTTP rate
|
|
40
|
+
limiter to 10,000 active client buckets. Expired entries are reclaimed
|
|
41
|
+
incrementally, and new clients fail closed when the limiter is full (#349).
|
|
42
|
+
|
|
43
|
+
### Security
|
|
44
|
+
|
|
45
|
+
- Code search now skips symlinked files, rejects directory aliases into excluded
|
|
46
|
+
paths, and streams Ruby fallback reads up to the requested result cap (#347).
|
|
47
|
+
- Tool response cache keys now include the active Rails application, preventing
|
|
48
|
+
identical requests from reusing another application scope's response (#348).
|
|
49
|
+
- Refresh locked dependencies to include `crass` 1.0.8, which fixes
|
|
50
|
+
GHSA-pq4g-8rxf-4g29 in the CSS sanitizer dependency chain (#343).
|
|
51
|
+
|
|
52
|
+
### Maintenance
|
|
53
|
+
|
|
54
|
+
- Refresh the mutation and demo-app lockfiles, including MCP 1.8.1, Rubydex
|
|
55
|
+
0.4.2, Rails 8.1.4, SQLite 2.10.1, Faraday 2.15.0, Mutant 0.17.1,
|
|
56
|
+
RuboCop 1.92.1, and compatible transitive updates (#343). Skunk remains on
|
|
57
|
+
0.5.4 because its 0.6 line conflicts with RubyCritic's `path_expander`
|
|
58
|
+
requirement; Reek remains on 6.5.x as required by RubyCritic 4.12.
|
|
59
|
+
|
|
60
|
+
### Deprecated
|
|
61
|
+
|
|
62
|
+
- `.cursorrules`, `.devinrules`, and `.codex/README.md` are no longer written by default. Cursor reads
|
|
63
|
+
`.cursor/rules/` and `AGENTS.md`, Devin does not read `.devinrules`, and Codex reads only `AGENTS.md`.
|
|
64
|
+
`.cursor/rules/`, `.devin/rules/`, and `AGENTS.md` are unchanged. Set
|
|
65
|
+
`config.output.legacy_agent_files = true` to keep writing the three files; the first run prints a
|
|
66
|
+
deprecation notice. The option and the files are removed in 6.0. Existing copies are never deleted.
|
|
67
|
+
|
|
10
68
|
## [5.3.0] - 2026-10-08
|
|
11
69
|
|
|
12
70
|
Confidence tags now reach controllers and the full view listing, and an opt-in Prism pass can upgrade
|
data/README.md
CHANGED
|
@@ -206,12 +206,9 @@ your-rails-app/
|
|
|
206
206
|
│ └── rails-mcp-tools.md full tool reference
|
|
207
207
|
│
|
|
208
208
|
├── 🟡 OpenAI Codex
|
|
209
|
-
│
|
|
210
|
-
│ └── .codex/
|
|
211
|
-
│ └── README.md local Codex setup notes
|
|
209
|
+
│ └── AGENTS.md project instructions for Codex
|
|
212
210
|
│
|
|
213
211
|
├── 🟢 Cursor
|
|
214
|
-
│ ├── .cursorrules legacy compat
|
|
215
212
|
│ └── .cursor/rules/
|
|
216
213
|
│ ├── rails-engineering.mdc alwaysApply: true (rules first)
|
|
217
214
|
│ ├── rails-project.mdc alwaysApply: true
|
|
@@ -220,7 +217,6 @@ your-rails-app/
|
|
|
220
217
|
│ └── rails-mcp-tools.mdc alwaysApply: true
|
|
221
218
|
│
|
|
222
219
|
├── 🔵 Devin
|
|
223
|
-
│ ├── .devinrules ≤5,800 chars (6K limit)
|
|
224
220
|
│ └── .devin/rules/
|
|
225
221
|
│ ├── rails-context.md project overview
|
|
226
222
|
│ └── rails-mcp-tools.md tool reference
|
|
@@ -374,10 +370,10 @@ rails-ai-bridge gives every client two things: **static context files** loaded a
|
|
|
374
370
|
| Client | Static files loaded automatically | MCP wiring |
|
|
375
371
|
|--------|----------------------------------|------------|
|
|
376
372
|
| **Claude Code** | `CLAUDE.md`, `.claude/rules/*.md` | Auto — reads `.mcp.json` |
|
|
377
|
-
| **Cursor** | `.
|
|
378
|
-
| **Devin** | `.
|
|
373
|
+
| **Cursor** | `.cursor/rules/*.mdc`, `AGENTS.md` | Auto — reads `.mcp.json` |
|
|
374
|
+
| **Devin** | `.devin/rules/*.md`, `AGENTS.md` | Manual — create `.devin/mcp.json` |
|
|
379
375
|
| **Copilot** | `.github/copilot-instructions.md`, `.github/instructions/` | Not supported natively |
|
|
380
|
-
| **Codex** | `AGENTS.md
|
|
376
|
+
| **Codex** | `AGENTS.md` | Via `.codex/mcp_servers.json` |
|
|
381
377
|
| **Gemini** | `GEMINI.md` | Via Gemini CLI config |
|
|
382
378
|
|
|
383
379
|
### Claude Code
|
|
@@ -405,11 +401,11 @@ Start your Rails server and point Cursor to `http://localhost:3000/mcp` (type: S
|
|
|
405
401
|
|
|
406
402
|
### Devin
|
|
407
403
|
|
|
408
|
-
Devin reads `.
|
|
404
|
+
Devin reads `.devin/rules/*.md` and `AGENTS.md` automatically. MCP requires one manual step.
|
|
409
405
|
|
|
410
406
|
**Step 1 — generate files:**
|
|
411
407
|
```bash
|
|
412
|
-
rails ai:bridge # all formats, including .
|
|
408
|
+
rails ai:bridge # all formats, including .devin/rules/ and AGENTS.md
|
|
413
409
|
```
|
|
414
410
|
|
|
415
411
|
**Step 2 — create `.devin/mcp.json`:**
|
|
@@ -437,7 +433,7 @@ MCP is not natively supported in the Copilot VS Code extension. The static files
|
|
|
437
433
|
|
|
438
434
|
### Codex
|
|
439
435
|
|
|
440
|
-
Codex reads `AGENTS.md` at the repository root. MCP can be configured in `.codex/mcp_servers.json`. Run `rails ai:bridge:codex` to regenerate `AGENTS.md
|
|
436
|
+
Codex reads `AGENTS.md` at the repository root. MCP can be configured in `.codex/mcp_servers.json`. Run `rails ai:bridge:codex` to regenerate `AGENTS.md`.
|
|
441
437
|
|
|
442
438
|
### HTTP transport (alternative for all clients)
|
|
443
439
|
|
|
@@ -605,6 +601,7 @@ The confidence and Prism settings also work on the `static_analysis` sub-object.
|
|
|
605
601
|
| `watcher_formats` | `:all` | Formats regenerated by `rails ai:watch` (e.g. `%i[claude cursor]` to limit churn) |
|
|
606
602
|
| `managed_region` | `false` | Confine generated output to a marked block so hand-authored content in `CLAUDE.md` & co. survives regeneration |
|
|
607
603
|
| `anti_hallucination_rules` | `true` | Include the shared verify-before-write block in every generated context file (markdown near the top, `.ai-context.json` as an `anti_hallucination_rules` key) |
|
|
604
|
+
| `legacy_agent_files` | `false` | Also write the deprecated `.cursorrules`, `.devinrules`, and `.codex/README.md`. Cursor reads `.cursor/rules/` and `AGENTS.md`, Devin does not read `.devinrules`, and Codex reads only `AGENTS.md`. Removed in 6.0 |
|
|
608
605
|
| `parallel_introspection` | `false` | Run introspectors concurrently (requires `concurrent-ruby`, which is already a Rails dependency) |
|
|
609
606
|
| `parallel_pool_size` | `4` | Max threads in the parallel pool; capped at the number of active introspectors so no idle threads are created |
|
|
610
607
|
| `parallel_timeout_seconds` | `10` | Per-introspector future timeout (seconds); timed-out introspectors return `{ error: "timed out after Ns" }` without blocking the others |
|
|
@@ -670,7 +667,7 @@ Always run `bin/rubocop` before committing.
|
|
|
670
667
|
wrap the generated part in the markers by hand before your first run to keep it.
|
|
671
668
|
|
|
672
669
|
Markdown provider files only (`CLAUDE.md`, `AGENTS.md`, `GEMINI.md`,
|
|
673
|
-
`.github/copilot-instructions.md
|
|
670
|
+
`.github/copilot-instructions.md`). `.ai-context.json` never
|
|
674
671
|
receives markers. Freshness skipping and `ai:doctor` staleness both read through the region,
|
|
675
672
|
so unchanged runs are still no-ops.
|
|
676
673
|
|
|
@@ -690,8 +687,8 @@ Every generated context file carries a short verify-before-write block so AI ass
|
|
|
690
687
|
query the live app (via the `rails_*` MCP tools) instead of inventing structure:
|
|
691
688
|
|
|
692
689
|
- Markdown files (`CLAUDE.md`, `AGENTS.md`, `GEMINI.md`, `.github/copilot-instructions.md`,
|
|
693
|
-
|
|
694
|
-
`.
|
|
690
|
+
and the split-rules files under `.claude/rules/`, `.cursor/rules/`, `.devin/rules/`,
|
|
691
|
+
`.github/instructions/`) open with a
|
|
695
692
|
`## Anti-hallucination rules` section near the top — after the freshness header, before
|
|
696
693
|
content sections — so it survives compact-mode trimming and stays inside the managed
|
|
697
694
|
region on regeneration.
|
|
@@ -835,7 +832,7 @@ Frontend introspectors (views, Turbo, Stimulus, assets) degrade gracefully — t
|
|
|
835
832
|
| `rails ai:bridge` | Generate all bridge files (skips unchanged) |
|
|
836
833
|
| `rails ai:bridge:full` | Generate all files in full mode (dumps everything) |
|
|
837
834
|
| `rails ai:bridge:claude` | Generate Claude Code files only |
|
|
838
|
-
| `rails ai:bridge:codex` | Generate Codex files only (`AGENTS.md`
|
|
835
|
+
| `rails ai:bridge:codex` | Generate Codex files only (`AGENTS.md`) |
|
|
839
836
|
| `rails ai:bridge:cursor` | Generate Cursor files only |
|
|
840
837
|
| `rails ai:bridge:devin` | Generate Devin files only |
|
|
841
838
|
| `rails ai:bridge:copilot` | Generate Copilot files only |
|
|
@@ -876,7 +873,8 @@ The gem parses `db/schema.rb` as text when no database is connected. Works in CI
|
|
|
876
873
|
|
|
877
874
|
## Requirements
|
|
878
875
|
|
|
879
|
-
- Ruby
|
|
876
|
+
- Ruby **>= 3.2** (blocking CI on 3.2, 3.3, 3.4; Ruby 4.0 is a non-blocking canary). See the [Ruby support policy](docs/ruby-version-support.md) for tested combinations.
|
|
877
|
+
- Rails >= 7.1, < 10.0 (tested on 7.1, 7.2, 8.0, 8.1)
|
|
880
878
|
- [mcp](https://github.com/modelcontextprotocol/ruby-sdk) gem (installed automatically)
|
|
881
879
|
- Optional: `listen` gem for watch mode, `ripgrep` for fast code search
|
|
882
880
|
|
data/SECURITY.md
CHANGED
|
@@ -29,6 +29,9 @@ please report it responsibly:
|
|
|
29
29
|
|
|
30
30
|
- All MCP tools are **read-only** and never modify your application or database.
|
|
31
31
|
- Code search (`rails_search_code`) uses `Open3.capture2` with array arguments to prevent shell injection.
|
|
32
|
+
Both backends skip symlinked files and reject directory aliases into excluded paths;
|
|
33
|
+
the Ruby fallback opens files with `File::NOFOLLOW` and streams lines so reaching
|
|
34
|
+
the result cap does not load the rest of a file.
|
|
32
35
|
- Symbol explanation (`rails_explain_symbol`) uses `Open3.capture3` with array arguments against a local `.codegraph/` index only (timeout enforced; never contacts a network service).
|
|
33
36
|
- File paths are validated against path traversal attacks, and invalid regex input
|
|
34
37
|
now returns a controlled tool response in the Ruby fallback path.
|
data/UPGRADING.md
CHANGED
|
@@ -1,5 +1,20 @@
|
|
|
1
1
|
# Upgrading rails-ai-bridge
|
|
2
2
|
|
|
3
|
+
## Upgrading from 5.3.x to the next release
|
|
4
|
+
|
|
5
|
+
**One behavior change.** `rails ai:bridge` no longer writes `.cursorrules`, `.devinrules`, or
|
|
6
|
+
`.codex/README.md`. No assistant needs them: Cursor reads `.cursor/rules/` and `AGENTS.md`, Devin does not
|
|
7
|
+
read `.devinrules`, and Codex reads only `AGENTS.md`. Nothing else changes, and the gem never deletes your
|
|
8
|
+
existing copies. Delete them when you are ready (and remove them from `.gitignore` or CI if you listed them).
|
|
9
|
+
|
|
10
|
+
To keep writing them until 6.0 removes the option:
|
|
11
|
+
|
|
12
|
+
```ruby
|
|
13
|
+
RailsAiBridge.configure { |config| config.output.legacy_agent_files = true }
|
|
14
|
+
```
|
|
15
|
+
|
|
16
|
+
---
|
|
17
|
+
|
|
3
18
|
## Upgrading from 5.2.x to 5.3.0
|
|
4
19
|
|
|
5
20
|
**No action is required.** One default changes what tools print.
|
data/docs/BEST_PRACTICES.md
CHANGED
|
@@ -50,17 +50,17 @@ Each AI client reads different files. Knowing which files matter for your tool h
|
|
|
50
50
|
| Client | Passive context (always loaded) | Live MCP | Notes |
|
|
51
51
|
|--------|---------------------------------|----------|-------|
|
|
52
52
|
| **Claude Code** | `CLAUDE.md`, `.claude/rules/*.md` | `.mcp.json` auto-detected | Rules injected per-session; MCP auto-wired via `.mcp.json` |
|
|
53
|
-
| **Cursor** | `.
|
|
54
|
-
| **Devin** | `.
|
|
53
|
+
| **Cursor** | `.cursor/rules/*.mdc`, `AGENTS.md` | `.mcp.json` auto-detected | `alwaysApply: true` rules loaded every turn; glob-scoped rules loaded per file |
|
|
54
|
+
| **Devin** | `.devin/rules/*.md`, `AGENTS.md` | Manual MCP config required | Reads `AGENTS.md`, `CLAUDE.md`, and the rules directory |
|
|
55
55
|
| **GitHub Copilot (VS Code)** | `.github/copilot-instructions.md`, `.github/instructions/*.instructions.md` | Not supported natively | `applyTo` glob patterns control which instructions file is injected |
|
|
56
|
-
| **OpenAI Codex** | `AGENTS.md
|
|
56
|
+
| **OpenAI Codex** | `AGENTS.md` | `.mcp.json` (when configured) | `AGENTS.md` at repo root is the primary context source |
|
|
57
57
|
| **Gemini (AI Studio / Code Assist)** | `GEMINI.md` | MCP via Gemini CLI | `GEMINI.md` provides the project briefing; MCP for live data |
|
|
58
58
|
|
|
59
59
|
### How MCP wiring works per client
|
|
60
60
|
|
|
61
61
|
- **Claude Code & Cursor**: `.mcp.json` at the project root is auto-detected. No manual setup — the client spawns `rails ai:serve` automatically.
|
|
62
62
|
- **Devin**: MCP is not auto-detected. Create `.devin/mcp.json` manually (see [docs/devin-setup.md](devin-setup.md) for the exact JSON and full walkthrough).
|
|
63
|
-
- **Codex**: Configure in `.codex/mcp_servers.json` or equivalent.
|
|
63
|
+
- **Codex**: Configure in `.codex/mcp_servers.json` or equivalent.
|
|
64
64
|
- **Copilot**: MCP is not natively supported via `.mcp.json`. The `rails_*` tools are documented in `.github/instructions/rails-mcp-tools.instructions.md` so Copilot knows about them, but cannot call them automatically.
|
|
65
65
|
|
|
66
66
|
### What "always loaded" means for token budgets
|
|
@@ -218,12 +218,12 @@ The gem only overwrites files it generated. Files you create with different name
|
|
|
218
218
|
1. The five `.cursor/rules/*.mdc` files cover different scopes — don't collapse them into one big always-on file.
|
|
219
219
|
2. `rails-engineering.mdc` and `rails-project.mdc` are the always-on rules. Keep them concise (< 100 lines each).
|
|
220
220
|
3. `rails-models.mdc` and `rails-controllers.mdc` use glob scoping — they only fire when you have model/controller files open.
|
|
221
|
-
4. `.cursorrules` is
|
|
221
|
+
4. `.cursorrules` is deprecated by Cursor and no longer generated by default. Delete an old copy; `.cursor/rules/` and `AGENTS.md` replace it.
|
|
222
222
|
5. MCP is auto-wired via `.mcp.json`. Run `rails ai:serve` once; Cursor keeps it alive.
|
|
223
223
|
|
|
224
224
|
### Devin
|
|
225
225
|
|
|
226
|
-
1.
|
|
226
|
+
1. Devin does not read `.devinrules`, so the gem no longer generates it. Context goes into `AGENTS.md` and `.devin/rules/`.
|
|
227
227
|
2. Devin also reads `AGENTS.md` — run `rails ai:bridge` (not just `rails ai:bridge:devin`) to keep both files current.
|
|
228
228
|
3. MCP requires a manual one-time step: create `.devin/mcp.json` with an absolute `cwd` path. See [docs/devin-setup.md](devin-setup.md) for the exact JSON.
|
|
229
229
|
4. If `bundle` is not on `PATH` (common with rbenv/rvm in Devin's environment), use the absolute shim path or switch to the HTTP transport (`rails ai:serve_http`).
|
|
@@ -240,7 +240,7 @@ The gem only overwrites files it generated. Files you create with different name
|
|
|
240
240
|
|
|
241
241
|
1. `AGENTS.md` is the entry point — Codex reads this at task start.
|
|
242
242
|
2. Keep personal preferences in `~/.codex/AGENTS.md`; use the repository `AGENTS.md` for shared guidance.
|
|
243
|
-
3.
|
|
243
|
+
3. Configure MCP in `.codex/mcp_servers.json` so Codex can call the live `rails_*` tools.
|
|
244
244
|
4. Codex benefits most from explicit conventions (test patterns, service object structure) — make sure `overrides.md` is activated.
|
|
245
245
|
|
|
246
246
|
### Gemini
|
|
@@ -336,13 +336,10 @@ Use this ordering as a starting point, not a replacement for live checks. When a
|
|
|
336
336
|
CLAUDE.md
|
|
337
337
|
AGENTS.md
|
|
338
338
|
GEMINI.md
|
|
339
|
-
.cursorrules
|
|
340
339
|
.cursor/rules/
|
|
341
|
-
.devinrules
|
|
342
340
|
.devin/rules/
|
|
343
341
|
.github/copilot-instructions.md
|
|
344
342
|
.github/instructions/
|
|
345
|
-
.codex/README.md
|
|
346
343
|
.mcp.json
|
|
347
344
|
config/rails_ai_bridge/overrides.md ← commit even when stub; remove guard when ready
|
|
348
345
|
```
|
data/docs/EXAMPLES.md
CHANGED
|
@@ -78,14 +78,11 @@ Captured output (abridged):
|
|
|
78
78
|
📝 Writing bridge files...
|
|
79
79
|
✅ .../demo_app/CLAUDE.md
|
|
80
80
|
✅ .../demo_app/AGENTS.md
|
|
81
|
-
✅ .../demo_app/.cursorrules
|
|
82
|
-
✅ .../demo_app/.devinrules
|
|
83
81
|
✅ .../demo_app/.github/copilot-instructions.md
|
|
84
82
|
✅ .../demo_app/GEMINI.md
|
|
85
83
|
✅ .../demo_app/.claude/rules/rails-context.md
|
|
86
84
|
✅ .../demo_app/.claude/rules/rails-schema.md
|
|
87
85
|
✅ .../demo_app/.claude/rules/rails-models.md
|
|
88
|
-
⏭️ .../demo_app/.codex/README.md (unchanged)
|
|
89
86
|
...
|
|
90
87
|
|
|
91
88
|
Done! Your AI assistants now understand your Rails app.
|
|
@@ -97,9 +94,9 @@ One run writes context for all 7 assistant targets. The committed files in
|
|
|
97
94
|
| Assistant target | File(s) | Size |
|
|
98
95
|
|---|---|---|
|
|
99
96
|
| Claude Code | `CLAUDE.md` + `.claude/rules/*.md` | 111 lines (compact) |
|
|
100
|
-
| OpenAI Codex | `AGENTS.md`
|
|
101
|
-
| Cursor | `.
|
|
102
|
-
| Devin | `.
|
|
97
|
+
| OpenAI Codex | `AGENTS.md` | 98 lines |
|
|
98
|
+
| Cursor | `.cursor/rules/*.mdc` | 108 lines |
|
|
99
|
+
| Devin | `.devin/rules/*.md` | 53 lines |
|
|
103
100
|
| GitHub Copilot | `.github/copilot-instructions.md` + `.github/instructions/*.md` | 136 lines |
|
|
104
101
|
| Gemini | `GEMINI.md` | 111 lines |
|
|
105
102
|
| JSON cache (not an assistant) | `.ai-context.json` (regenerable cache, not committed) | — |
|
data/docs/GUIDE.md
CHANGED
|
@@ -80,7 +80,6 @@ rails ai:bridge
|
|
|
80
80
|
```
|
|
81
81
|
|
|
82
82
|
- CLAUDE.md ≤150 lines
|
|
83
|
-
- .devinrules ≤5,800 characters
|
|
84
83
|
- copilot-instructions.md ≤500 lines
|
|
85
84
|
- Files contain a project overview + MCP tool reference
|
|
86
85
|
- AI uses MCP tools for detailed data on-demand
|
|
@@ -139,25 +138,31 @@ end
|
|
|
139
138
|
| `.claude/rules/rails-models.md` | Model listing with associations | Includes `tier: …` per ActiveRecord model; adds **Non-ActiveRecord classes (POJO/Service)** for plain Ruby classes under `app/models`. |
|
|
140
139
|
| `.claude/rules/rails-mcp-tools.md` | Full MCP tool reference | Parameters, detail levels, pagination, workflow guide. |
|
|
141
140
|
|
|
142
|
-
### Cursor (
|
|
141
|
+
### Cursor (5 files)
|
|
143
142
|
|
|
144
143
|
| File | Purpose | Notes |
|
|
145
144
|
|------|---------|-------|
|
|
146
|
-
| `.cursorrules` | Legacy context file | Compact mode: engineering rules + stack + MCP (aligned with Copilot order). |
|
|
147
145
|
| `.cursor/rules/rails-engineering.mdc` | Engineering essentials | `alwaysApply: true` — strong params, auth, N+1, security; points to overrides + full docs. |
|
|
148
146
|
| `.cursor/rules/rails-project.mdc` | Project overview | `alwaysApply: true` — stack counts, endpoint focus, gems (capped), `routes_stack_line`. |
|
|
149
147
|
| `.cursor/rules/rails-models.mdc` | Model reference | `globs: app/models/**/*.rb` — auto-attaches when editing models; rows are ordered by task relevance. |
|
|
150
148
|
| `.cursor/rules/rails-controllers.mdc` | Controller reference | `globs: app/controllers/**/*.rb` — auto-attaches when editing controllers. |
|
|
151
149
|
| `.cursor/rules/rails-mcp-tools.mdc` | MCP tool reference | `alwaysApply: true` — always available. |
|
|
152
150
|
|
|
153
|
-
### Devin (
|
|
151
|
+
### Devin (2 files)
|
|
154
152
|
|
|
155
153
|
| File | Purpose | Notes |
|
|
156
154
|
|------|---------|-------|
|
|
157
|
-
| `.devinrules` | Main context file | Hard-capped at 5,800 chars (Devin's 6K limit). Truncated silently if exceeded. |
|
|
158
155
|
| `.devin/rules/rails-context.md` | Project overview | New Devin rules format. |
|
|
159
156
|
| `.devin/rules/rails-mcp-tools.md` | MCP tool reference | Compact — respects 6K per-file limit. |
|
|
160
157
|
|
|
158
|
+
### Deprecated files
|
|
159
|
+
|
|
160
|
+
`.cursorrules`, `.devinrules`, and `.codex/README.md` are no longer written by default. Cursor reads
|
|
161
|
+
`.cursor/rules/` and `AGENTS.md`, Devin reads `AGENTS.md` and `.devin/rules/` (it does not read
|
|
162
|
+
`.devinrules`), and Codex reads only `AGENTS.md`. Copies you already have stay in place; delete them when
|
|
163
|
+
you are ready. Set `config.output.legacy_agent_files = true` to keep writing them until 6.0, which removes
|
|
164
|
+
the option. The first run with the option on prints a deprecation notice.
|
|
165
|
+
|
|
161
166
|
### GitHub Copilot (4 files)
|
|
162
167
|
|
|
163
168
|
| File | Purpose | Notes |
|
|
@@ -197,7 +202,7 @@ query the `rails_*` MCP tools for columns, associations, and routes; mark guesse
|
|
|
197
202
|
`RailsAiBridge::Serializers::AntiHallucinationRules` — a single source of truth.
|
|
198
203
|
|
|
199
204
|
The block is injected into all markdown outputs (main context files **and** the
|
|
200
|
-
split-rules files under `.claude/rules/`, `.cursor/rules/`, `.devin/rules/`,
|
|
205
|
+
split-rules files under `.claude/rules/`, `.cursor/rules/`, `.devin/rules/`,
|
|
201
206
|
`.github/instructions/`) near the top, so it survives compact-mode bottom-trimming and
|
|
202
207
|
Devin's 5,800-character cap, and it is always inside the managed region when
|
|
203
208
|
`config.output.managed_region` is enabled.
|
|
@@ -215,9 +220,9 @@ Disable with `config.output.anti_hallucination_rules = false` (default: `true`).
|
|
|
215
220
|
| `rails ai:bridge` | compact | all | Generate all bridge files |
|
|
216
221
|
| `rails ai:bridge:full` | full | all | Generate all files in full mode |
|
|
217
222
|
| `rails ai:bridge:claude` | compact | Claude | CLAUDE.md + .claude/rules/ |
|
|
218
|
-
| `rails ai:bridge:codex` | compact | Codex | AGENTS.md
|
|
219
|
-
| `rails ai:bridge:cursor` | compact | Cursor | .
|
|
220
|
-
| `rails ai:bridge:devin` | compact | Devin | .
|
|
223
|
+
| `rails ai:bridge:codex` | compact | Codex | AGENTS.md |
|
|
224
|
+
| `rails ai:bridge:cursor` | compact | Cursor | .cursor/rules/ |
|
|
225
|
+
| `rails ai:bridge:devin` | compact | Devin | .devin/rules/ |
|
|
221
226
|
| `rails ai:bridge:copilot` | compact | Copilot | copilot-instructions.md + .github/instructions/ |
|
|
222
227
|
| `rails ai:bridge:json` | — | JSON | .ai-context.json |
|
|
223
228
|
| `CONTEXT_MODE=full rails ai:bridge:claude` | full | Claude | Full dump for Claude only |
|
|
@@ -286,7 +291,7 @@ RailsAiBridge.generate_context(
|
|
|
286
291
|
```ruby
|
|
287
292
|
# config/initializers/rails_ai_bridge.rb
|
|
288
293
|
RailsAiBridge.configure do |config|
|
|
289
|
-
# Regenerates CLAUDE.md + .claude/rules/* and .
|
|
294
|
+
# Regenerates CLAUDE.md + .claude/rules/* and .cursor/rules/*
|
|
290
295
|
# (split-rule directories are also churned when split_rules: true, the default)
|
|
291
296
|
config.watcher_formats = %i[claude cursor]
|
|
292
297
|
end
|
|
@@ -450,6 +455,22 @@ Returns application configuration. No parameters.
|
|
|
450
455
|
|
|
451
456
|
**Returns:** cache store, session store, timezone, middleware stack, initializers, credentials keys, current attributes.
|
|
452
457
|
|
|
458
|
+
#### Timezone facts
|
|
459
|
+
|
|
460
|
+
The raw `:config` payload includes `timezone` (the configured `config.time_zone`)
|
|
461
|
+
and `timezone_confirmed`. Confirmation is `true` when the current thread's
|
|
462
|
+
`Time.zone` and the configured zone resolve to the same IANA identifier. Rails
|
|
463
|
+
names such as `Eastern Time (US & Canada)` and IANA names such as
|
|
464
|
+
`America/New_York` are both supported.
|
|
465
|
+
|
|
466
|
+
Confirmation is `false` when the runtime zone is unavailable or different, for
|
|
467
|
+
example inside `Time.use_zone` with another zone. It describes the introspecting
|
|
468
|
+
thread at the time of the read, not every request's timezone. `rails_get_config`
|
|
469
|
+
and serializers retain their existing timezone rendering; the flag is raw
|
|
470
|
+
metadata. Config introspection requires boot; static mode reports it as skipped
|
|
471
|
+
and does not infer timezone settings from `db/schema.rb`. Broader timezone
|
|
472
|
+
output and offline support remain tracked in #342.
|
|
473
|
+
|
|
453
474
|
```
|
|
454
475
|
rails_get_config()
|
|
455
476
|
→ Cache: redis_cache_store, Session: cookie_store, TZ: UTC, ...
|
|
@@ -514,7 +535,7 @@ rails_search_code(pattern: "def create", path: "app/controllers", file_type: "rb
|
|
|
514
535
|
→ First 50 matches under app/controllers
|
|
515
536
|
```
|
|
516
537
|
|
|
517
|
-
**Security:** Uses `Open3.capture2` with array arguments (no shell injection). Validates `file_type`. Blocks path traversal.
|
|
538
|
+
**Security:** Uses `Open3.capture2` with array arguments (no shell injection). Validates `file_type`. Blocks path traversal. Both backends skip symlinked files and reject directory aliases into `excluded_paths`. The Ruby fallback streams lines and stops when the result cap is reached. Optional wall-clock limit per call: `config.search_code_timeout_seconds` (default 5; set `0` to disable).
|
|
518
539
|
|
|
519
540
|
### rails_search_semantic
|
|
520
541
|
|
|
@@ -551,14 +572,23 @@ Runs a single read-only SELECT statement on the app's established ActiveRecord c
|
|
|
551
572
|
|
|
552
573
|
| Param | Type | Description |
|
|
553
574
|
|-------|------|-------------|
|
|
554
|
-
| `sql` | string | **Required.** A single plain SELECT statement.
|
|
555
|
-
| `row_limit` | integer | Max rows (hard cap 100). Defaults: 20 (standard), 100 (full). |
|
|
556
|
-
| `detail` | string | `summary` (columns + row count), `standard` (default), `full`. |
|
|
575
|
+
| `sql` | string | **Required.** A single plain SELECT statement; one trailing semicolon is allowed. Multiple statements, CTEs (`WITH`), and mutating/locking clauses are rejected. |
|
|
576
|
+
| `row_limit` | integer | Max rows (hard cap 100). Defaults: 20 (standard), 100 (summary/full). |
|
|
577
|
+
| `detail` | string | `summary` (columns + bounded row count + truncation flag), `standard` (default), `full`. |
|
|
557
578
|
|
|
558
579
|
**Opt-in:** registered only when `config.enable_data_tools = true` (default `false`).
|
|
559
580
|
|
|
560
581
|
**Security:** SELECT-only allowlist (CTEs rejected in v1 — mutating CTEs allow writes inside `WITH`); `FOR UPDATE`/`FOR SHARE`/`LOCK IN SHARE MODE` and `SELECT ... INTO` (including `INTO OUTFILE`) rejected. On PostgreSQL the statement runs inside a `READ ONLY` transaction with `statement_timeout`; on other adapters the keyword guard is best-effort. Hard 100-row cap, 5s statement timeout. Credential-like columns (`password`, `token`, `secret`, `api_key`, `auth`, `password_digest`, `secret_access_key`, …) are replaced with `[redacted]` — best-effort: column aliases can bypass the match. Runs on the app's existing connection, so introspection exclusions (`excluded_models`/`excluded_tables`) do not restrict it.
|
|
561
582
|
|
|
583
|
+
The row cap is enforced in SQL before ActiveRecord materializes the result, fetching
|
|
584
|
+
at most `row_limit + 1` rows (maximum 101) to detect truncation. Existing SQL
|
|
585
|
+
`LIMIT`/`OFFSET` clauses are preserved. Use unique column aliases for portable
|
|
586
|
+
queries, because the SELECT runs as a derived table. `row_count` is the bounded count, not the
|
|
587
|
+
query's unrestricted total: it is exact when `truncated` is `false`; when `true`,
|
|
588
|
+
more rows matched than the reported count. Summary uses the same bound and
|
|
589
|
+
includes `truncated`, but omits `rows`. The cap bounds result materialization;
|
|
590
|
+
sorting, aggregation, and other database work remain subject to the timeout.
|
|
591
|
+
|
|
562
592
|
### rails_read_logs
|
|
563
593
|
|
|
564
594
|
Returns a redacted tail of a log file under the app's `log/` directory as compact JSON.
|
|
@@ -775,7 +805,7 @@ Set `config.require_http_auth = true` if the endpoint must not accept anonymous
|
|
|
775
805
|
|
|
776
806
|
### Codex
|
|
777
807
|
|
|
778
|
-
This fork adds Codex support through `AGENTS.md
|
|
808
|
+
This fork adds Codex support through `AGENTS.md`.
|
|
779
809
|
|
|
780
810
|
- Run `rails ai:bridge:codex` to regenerate Codex guidance.
|
|
781
811
|
- Commit `AGENTS.md` for shared repository instructions.
|
|
@@ -811,6 +841,7 @@ RailsAiBridge.configure do |config|
|
|
|
811
841
|
|
|
812
842
|
# Anti-hallucination rules block in every generated file (default: true)
|
|
813
843
|
# config.output.anti_hallucination_rules = true
|
|
844
|
+
# config.output.legacy_agent_files = false # true also writes deprecated .cursorrules, .devinrules, .codex/README.md
|
|
814
845
|
|
|
815
846
|
# Formats regenerated by `rails ai:watch` (default: :all). Narrow to limit churn.
|
|
816
847
|
# config.watcher_formats = %i[claude cursor]
|
|
@@ -823,7 +854,7 @@ RailsAiBridge.configure do |config|
|
|
|
823
854
|
# Optional markdown merged into compact Copilot + Codex (default: config/rails_ai_bridge/overrides.md)
|
|
824
855
|
# config.assistant_overrides_path = "config/rails_ai_bridge/overrides.md"
|
|
825
856
|
|
|
826
|
-
# Model names shown in compact copilot-instructions / AGENTS
|
|
857
|
+
# Model names shown in compact copilot-instructions / AGENTS (0 = MCP pointer only)
|
|
827
858
|
# config.copilot_compact_model_list_limit = 5
|
|
828
859
|
# config.codex_compact_model_list_limit = 3
|
|
829
860
|
|
|
@@ -918,10 +949,11 @@ The settings `confidence_tags_enabled`, `prism_enabled`, and `prism_max_files` w
|
|
|
918
949
|
| `http_log_json` | Boolean | `false` | Structured JSON log line per HTTP MCP response |
|
|
919
950
|
| `server_name` | String | `"rails-ai-bridge"` | MCP server name |
|
|
920
951
|
| `assistant_overrides_path` | String | `nil` → `config/rails_ai_bridge/overrides.md` | Markdown merged into compact Copilot + Codex |
|
|
921
|
-
| `copilot_compact_model_list_limit` | Integer | `5` | Max model rows in copilot-instructions
|
|
952
|
+
| `copilot_compact_model_list_limit` | Integer | `5` | Max model rows in copilot-instructions (`0` = none) |
|
|
922
953
|
| `codex_compact_model_list_limit` | Integer | `3` | Max model rows in `AGENTS.md` (`0` = none) |
|
|
923
954
|
| `watcher_formats` | Symbol / Array | `:all` | Formats regenerated by `rails ai:watch`. Set to e.g. `%i[claude cursor]` to skip formats you don't use during active development. |
|
|
924
955
|
| `anti_hallucination_rules` | Boolean | `true` | Include the shared `## Anti-hallucination rules` block in every generated context file (markdown near the top; `.ai-context.json` as an `anti_hallucination_rules` key) |
|
|
956
|
+
| `legacy_agent_files` | Boolean | `false` | Also write the deprecated `.cursorrules`, `.devinrules`, and `.codex/README.md`. Removed in 6.0. |
|
|
925
957
|
| `parallel_introspection` | Boolean | `false` | Run introspectors concurrently using a `Concurrent::FixedThreadPool`. Requires `concurrent-ruby` (already a Rails transitive dep). Automatically disabled when the ActiveRecord connection pool has only one slot. |
|
|
926
958
|
| `parallel_pool_size` | Integer | `4` | Upper bound on pool threads. Actual size is `min(introspector_count, parallel_pool_size)` — no idle threads are created. Only relevant when `parallel_introspection` is `true`. |
|
|
927
959
|
| `parallel_timeout_seconds` | Integer | `10` | Seconds each future may run before being cancelled. Timed-out introspectors return `{ error: "timed out after Ns" }`. Also used as the `wait_for_termination` grace period. Only relevant when `parallel_introspection` is `true`. |
|
|
@@ -930,6 +962,32 @@ The settings `confidence_tags_enabled`, `prism_enabled`, and `prism_max_files` w
|
|
|
930
962
|
| `prism_enabled` | Boolean | `false` | Turns on the Prism pass. Strong params that Prism finds as methods in the controller source render as `[VERIFIED]`. Needs Prism, a default gem on Ruby 3.3+. |
|
|
931
963
|
| `prism_max_files` | Integer | `500` | Caps the files the Prism pass reads per introspection run. |
|
|
932
964
|
|
|
965
|
+
### Tool-call observability
|
|
966
|
+
|
|
967
|
+
Every MCP invocation emits `rails_ai_bridge.tool.call` through
|
|
968
|
+
`ActiveSupport::Notifications`. Its payload keeps `tool_name` and `arguments` and
|
|
969
|
+
adds `success` plus `error_class`. `success` is false for an MCP error response or
|
|
970
|
+
a raised exception; `error_class` is populated only for raised exceptions. Use the
|
|
971
|
+
notification event's duration instead of adding timing labels, and avoid exporting
|
|
972
|
+
raw `arguments` because they may contain application data.
|
|
973
|
+
|
|
974
|
+
```ruby
|
|
975
|
+
ActiveSupport::Notifications.subscribe("rails_ai_bridge.tool.call") do |*args|
|
|
976
|
+
event = ActiveSupport::Notifications::Event.new(*args)
|
|
977
|
+
payload = event.payload
|
|
978
|
+
|
|
979
|
+
Rails.logger.info(
|
|
980
|
+
event: event.name,
|
|
981
|
+
tool: payload[:tool_name],
|
|
982
|
+
success: payload[:success],
|
|
983
|
+
error_class: payload[:error_class],
|
|
984
|
+
duration_ms: event.duration.round(1)
|
|
985
|
+
)
|
|
986
|
+
end
|
|
987
|
+
```
|
|
988
|
+
|
|
989
|
+
This example intentionally excludes `payload[:arguments]`.
|
|
990
|
+
|
|
933
991
|
---
|
|
934
992
|
|
|
935
993
|
## Introspectors — Full List
|
|
@@ -1028,7 +1086,6 @@ rails ai:bridge # all formats at once
|
|
|
1028
1086
|
### Cursor
|
|
1029
1087
|
|
|
1030
1088
|
**Passive context (loaded automatically):**
|
|
1031
|
-
- `.cursorrules` — legacy compat file, loaded at session start
|
|
1032
1089
|
- `.cursor/rules/*.mdc` — MDC rules with activation modes:
|
|
1033
1090
|
|
|
1034
1091
|
| Rule file | Activation |
|
|
@@ -1072,7 +1129,7 @@ Then start your Rails server (`bin/rails server`) and point Cursor to `http://lo
|
|
|
1072
1129
|
|
|
1073
1130
|
**Regenerate context:**
|
|
1074
1131
|
```bash
|
|
1075
|
-
rails ai:bridge:cursor # .
|
|
1132
|
+
rails ai:bridge:cursor # .cursor/rules/
|
|
1076
1133
|
```
|
|
1077
1134
|
|
|
1078
1135
|
---
|
|
@@ -1080,7 +1137,6 @@ rails ai:bridge:cursor # .cursorrules + .cursor/rules/
|
|
|
1080
1137
|
### Devin
|
|
1081
1138
|
|
|
1082
1139
|
**Passive context (loaded automatically):**
|
|
1083
|
-
- `.devinrules` — compact project overview, hard-capped at 5,800 chars (Devin's 6K limit)
|
|
1084
1140
|
- `.devin/rules/rails-context.md` — project overview (full version, also capped at 5,800 chars)
|
|
1085
1141
|
- `.devin/rules/rails-mcp-tools.md` — MCP tool reference
|
|
1086
1142
|
- `AGENTS.md` — Devin also reads AGENTS.md as repo-level instructions
|
|
@@ -1089,7 +1145,7 @@ rails ai:bridge:cursor # .cursorrules + .cursor/rules/
|
|
|
1089
1145
|
|
|
1090
1146
|
**Step 1 — Generate the Devin context files:**
|
|
1091
1147
|
```bash
|
|
1092
|
-
rails ai:bridge:devin # .
|
|
1148
|
+
rails ai:bridge:devin # .devin/rules/
|
|
1093
1149
|
rails ai:bridge:codex # AGENTS.md (Devin also reads this)
|
|
1094
1150
|
# or generate everything at once:
|
|
1095
1151
|
rails ai:bridge
|
|
@@ -1166,13 +1222,12 @@ rails ai:bridge:copilot # .github/copilot-instructions.md + .github/instructio
|
|
|
1166
1222
|
|
|
1167
1223
|
**Passive context:**
|
|
1168
1224
|
- `AGENTS.md` — primary context file, read by Codex at session start
|
|
1169
|
-
- `.codex/README.md` — local Codex setup notes generated by the install generator
|
|
1170
1225
|
|
|
1171
|
-
**MCP tools:** Configurable via `.codex/mcp_servers.json` or equivalent Codex MCP config.
|
|
1226
|
+
**MCP tools:** Configurable via `.codex/mcp_servers.json` or equivalent Codex MCP config.
|
|
1172
1227
|
|
|
1173
1228
|
**Regenerate context:**
|
|
1174
1229
|
```bash
|
|
1175
|
-
rails ai:bridge:codex # AGENTS.md
|
|
1230
|
+
rails ai:bridge:codex # AGENTS.md
|
|
1176
1231
|
```
|
|
1177
1232
|
|
|
1178
1233
|
---
|
data/docs/devin-setup.md
CHANGED
|
@@ -19,14 +19,12 @@ Devin CLI reads the following files from your project root without any configura
|
|
|
19
19
|
|
|
20
20
|
| File | Purpose |
|
|
21
21
|
|------|---------|
|
|
22
|
-
| `.devinrules` | Primary context file. Hard-capped at 5,800 characters (Devin enforces a 6K limit). Contains the most critical project overview. |
|
|
23
22
|
| `.devin/rules/*.md` | Supplementary rule files. Devin reads all Markdown files in this directory. |
|
|
24
|
-
| `AGENTS.md` |
|
|
23
|
+
| `AGENTS.md` | Repo-level instructions. Devin reads this alongside the rules directory. |
|
|
25
24
|
|
|
26
25
|
The rails-ai-bridge generator produces:
|
|
27
26
|
|
|
28
|
-
- `.
|
|
29
|
-
- `.devin/rules/rails-context.md` — project overview content that overflows from `.devinrules`
|
|
27
|
+
- `.devin/rules/rails-context.md` — project overview content
|
|
30
28
|
- `.devin/rules/rails-mcp-tools.md` — MCP tool reference so Devin knows what tools are available
|
|
31
29
|
- `AGENTS.md` — full project context and conventions in codex format
|
|
32
30
|
|
|
@@ -42,7 +40,7 @@ Run the Devin-specific generator:
|
|
|
42
40
|
bundle exec rails ai:bridge:devin
|
|
43
41
|
```
|
|
44
42
|
|
|
45
|
-
This writes `.
|
|
43
|
+
This writes `.devin/rules/rails-context.md`, and `.devin/rules/rails-mcp-tools.md`. Run `rails ai:bridge:codex` as well to write `AGENTS.md`, which Devin also reads. Unchanged files are skipped (SHA256 fingerprinting prevents unnecessary writes).
|
|
46
44
|
|
|
47
45
|
To generate context files for all supported AI tools at once:
|
|
48
46
|
|
|
@@ -132,13 +130,13 @@ If this command exits immediately with an error, the problem is in your Rails en
|
|
|
132
130
|
|
|
133
131
|
Use the two layers for different purposes:
|
|
134
132
|
|
|
135
|
-
**Static files for orientation** — at the start of a session, Devin reads
|
|
133
|
+
**Static files for orientation** — at the start of a session, Devin reads `AGENTS.md` and `.devin/rules/` to understand the project structure, conventions, and domain. This costs no tool calls and happens automatically.
|
|
136
134
|
|
|
137
135
|
**MCP tools for drill-down** — when Devin needs specific information (the associations on a particular model, the routes for a namespace, test coverage for a controller), it calls the appropriate MCP tool. This returns current data directly from your running application.
|
|
138
136
|
|
|
139
137
|
A typical session looks like:
|
|
140
138
|
|
|
141
|
-
1. Devin loads
|
|
139
|
+
1. Devin loads `AGENTS.md` and `.devin/rules/` — understands the project at a high level.
|
|
142
140
|
2. Devin calls `rails_get_schema` to inspect the tables relevant to the task.
|
|
143
141
|
3. Devin calls `rails_get_model_details` with `detail: full` for the specific model it is working on.
|
|
144
142
|
4. Devin calls `rails_get_routes` to understand the routing structure.
|
|
@@ -257,7 +255,6 @@ Devin will call `rails_list_registry`, review the options, and call `rails_resol
|
|
|
257
255
|
|
|
258
256
|
| File | Generator | Checked in? |
|
|
259
257
|
|------|-----------|-------------|
|
|
260
|
-
| `.devinrules` | `rails ai:bridge:devin` | Yes |
|
|
261
258
|
| `.devin/rules/rails-context.md` | `rails ai:bridge:devin` | Yes |
|
|
262
259
|
| `.devin/rules/rails-mcp-tools.md` | `rails ai:bridge:devin` | Yes |
|
|
263
260
|
| `AGENTS.md` | `rails ai:bridge:devin` | Yes |
|