rails-ai-context 5.38.1 → 5.38.2
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/CHANGELOG.md +74 -0
- data/README.md +2 -2
- data/docs/ARCHITECTURE.md +18 -16
- data/docs/CONFIGURATION.md +7 -4
- data/docs/CUSTOM_TOOLS.md +1 -1
- data/docs/FAQ.md +11 -7
- data/docs/GUIDE.md +65 -46
- data/docs/PROMPTS.md +1 -1
- data/docs/QUICKSTART.md +1 -1
- data/docs/RECIPES.md +2 -2
- data/docs/SETUP.md +13 -11
- data/docs/TROUBLESHOOTING.md +4 -6
- data/lib/generators/rails_ai_context/install/install_generator.rb +4 -0
- data/lib/rails_ai_context/cli/tool_runner.rb +1 -1
- data/lib/rails_ai_context/configuration.rb +8 -2
- data/lib/rails_ai_context/context_file_report.rb +9 -3
- data/lib/rails_ai_context/doctor.rb +9 -5
- data/lib/rails_ai_context/initializer_settings.rb +10 -2
- data/lib/rails_ai_context/install/ai_tool.rb +52 -8
- data/lib/rails_ai_context/install/cleanup.rb +19 -2
- data/lib/rails_ai_context/install/program.rb +8 -1
- data/lib/rails_ai_context/introspectors/test_introspector.rb +18 -1
- data/lib/rails_ai_context/serializers/base.rb +5 -1
- data/lib/rails_ai_context/serializers/budget.rb +124 -0
- data/lib/rails_ai_context/serializers/claude_rules_serializer.rb +29 -119
- data/lib/rails_ai_context/serializers/compact_serializer_helper.rb +21 -148
- data/lib/rails_ai_context/serializers/context_file_serializer.rb +76 -62
- data/lib/rails_ai_context/serializers/copilot_instructions_serializer.rb +28 -71
- data/lib/rails_ai_context/serializers/cursor_rules_serializer.rb +30 -118
- data/lib/rails_ai_context/serializers/load_plan.rb +64 -0
- data/lib/rails_ai_context/serializers/markdown_serializer.rb +23 -120
- data/lib/rails_ai_context/serializers/model_section.rb +108 -0
- data/lib/rails_ai_context/serializers/opencode_rules_serializer.rb +15 -46
- data/lib/rails_ai_context/serializers/root_file.rb +16 -0
- data/lib/rails_ai_context/serializers/rule_scope.rb +73 -0
- data/lib/rails_ai_context/serializers/section_facts.rb +14 -4
- data/lib/rails_ai_context/serializers/section_marker_writer.rb +16 -2
- data/lib/rails_ai_context/serializers/stack_overview_helper.rb +119 -73
- data/lib/rails_ai_context/serializers/stack_sections.rb +63 -0
- data/lib/rails_ai_context/serializers/tool_guide_helper.rb +71 -170
- data/lib/rails_ai_context/server.rb +1 -1
- data/lib/rails_ai_context/tools/base_tool.rb +13 -1
- data/lib/rails_ai_context/tools/get_context.rb +1 -1
- data/lib/rails_ai_context/tools/safe_call.rb +34 -15
- data/lib/rails_ai_context/tools/search_code.rb +1 -1
- data/lib/rails_ai_context/tools/validate.rb +1 -1
- data/lib/rails_ai_context/version.rb +1 -1
- data/lib/rails_ai_context/watcher.rb +2 -0
- metadata +7 -6
- data/lib/rails_ai_context/serializers/claude_serializer.rb +0 -42
- data/lib/rails_ai_context/serializers/context_mode_dispatch.rb +0 -20
- data/lib/rails_ai_context/serializers/copilot_serializer.rb +0 -43
- data/lib/rails_ai_context/serializers/opencode_serializer.rb +0 -41
- data/lib/rails_ai_context/serializers/test_command_detection.rb +0 -15
checksums.yaml
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
---
|
|
2
2
|
SHA256:
|
|
3
|
-
metadata.gz:
|
|
4
|
-
data.tar.gz:
|
|
3
|
+
metadata.gz: 51468955210c3dfe5b635691b5408be3f813f674380481115c098fab27973eae
|
|
4
|
+
data.tar.gz: 5fa9d2735c18d79c6bbd3f3e23205f9c5ffc8bd6728bae6feb0dcbf5cbdaaa1f
|
|
5
5
|
SHA512:
|
|
6
|
-
metadata.gz:
|
|
7
|
-
data.tar.gz:
|
|
6
|
+
metadata.gz: 0bdc32c9fd9e5d09c666fc59690b38f5808383a676d3e40dbd026f0c97c2b3f00b79ad80c16b0defe34052df83a82e7e64c8e9f64195b376fb6190ba259c04a7
|
|
7
|
+
data.tar.gz: c5dedfae2bdbb103d435cc38673ac35a077ae60d6c480bded1c93b6ba4146bacfd7c98bf3c06b795e74261b86f51438c1b1a4b82dd525959213fc49b8ce6eb70
|
data/CHANGELOG.md
CHANGED
|
@@ -5,6 +5,80 @@ All notable changes to this project will be documented in this file.
|
|
|
5
5
|
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
|
|
6
6
|
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
|
|
7
7
|
|
|
8
|
+
## [5.38.2] - 2026-10-29
|
|
9
|
+
|
|
10
|
+
### Added
|
|
11
|
+
|
|
12
|
+
- **Every tool answer ends with one line** asking the AI to offer you a GitHub
|
|
13
|
+
issue when rails-ai-context itself answered wrong, missed something or
|
|
14
|
+
failed, or could do better. It comes once per answer (a composite tool's
|
|
15
|
+
parts leave it out), under a `_report` key in a JSON answer, and costs about
|
|
16
|
+
40 tokens. `config.report_issue_line = false` leaves it out.
|
|
17
|
+
- **The root file says when model tests are not named the usual way.** An
|
|
18
|
+
app where more than a quarter of the model specs are named
|
|
19
|
+
`user_model_spec.rb` gets one clause on the test command line pointing at
|
|
20
|
+
`rails_get_test_info`. Agents had guessed `spec/models/user_spec.rb`; naming
|
|
21
|
+
both paths instead made them open the first without looking.
|
|
22
|
+
|
|
23
|
+
### Changed
|
|
24
|
+
|
|
25
|
+
- **The root content is written once, into a file every chosen AI tool
|
|
26
|
+
reads.** Cursor reads `CLAUDE.md` and `AGENTS.md` as it reads its own
|
|
27
|
+
always-on rules, and VS Code Copilot attaches both beside
|
|
28
|
+
`copilot-instructions.md`, so a copy for each tool loaded the same text two
|
|
29
|
+
or three times in one session. `AGENTS.md` now carries it. `CLAUDE.md` holds
|
|
30
|
+
only `@AGENTS.md`, which Claude Code expands at launch, unless Claude Code is
|
|
31
|
+
the only tool chosen. `.github/copilot-instructions.md` stays a whole copy,
|
|
32
|
+
byte for byte the same as `AGENTS.md`, because most Copilot surfaces read no
|
|
33
|
+
other file. On a 149-model app the files Claude Code loads at session start
|
|
34
|
+
went from about 13,400 tokens to about 5,000.
|
|
35
|
+
- **`.cursorrules` is no longer written.** Cursor calls it legacy. A run
|
|
36
|
+
takes out the block an earlier release wrote and keeps your own lines; a
|
|
37
|
+
file that held only the block is deleted. Picking Cursor writes `AGENTS.md`.
|
|
38
|
+
- **The overview and tools rules are written only where no root file states
|
|
39
|
+
them,** that is with `generate_root_files = false`: `.claude/rules/rails-context.md`
|
|
40
|
+
and `rails-mcp-tools.md`, `.cursor/rules/rails-project.mdc` and
|
|
41
|
+
`rails-mcp-tools.mdc`, `.github/instructions/rails-context.instructions.md`
|
|
42
|
+
and `rails-mcp-tools.instructions.md`. A rules file an earlier run wrote and
|
|
43
|
+
this one does not is removed, and the run reports `Removed: <path>` or
|
|
44
|
+
`Removed the generated block from <path>`. `doctor` counts such a file as
|
|
45
|
+
out of date. The tools rule written then carries the root file's guide, loads
|
|
46
|
+
in every session in Cursor too, and no longer carries a table of every tool.
|
|
47
|
+
- **Every context file has a byte budget.** The compact root file stays within
|
|
48
|
+
12,000 bytes as well as `claude_max_lines`, full mode within 24,000, a rules
|
|
49
|
+
file within 8,000 and a tools rule that stands in for the root file within
|
|
50
|
+
12,000. A list line is at most 240 characters and ends with `...N more`; the
|
|
51
|
+
tools answer the rest, and a cut services or jobs list names the tool that has
|
|
52
|
+
it whole. A file cut to fit says so where the cut is. These files share the agent's context
|
|
53
|
+
with your own instructions, and Codex reads at most 32 KiB of project docs in
|
|
54
|
+
all.
|
|
55
|
+
- **The root file names its 10 most connected models,** each on one line, and
|
|
56
|
+
where a list is cut, says it is whole in `rails_get_model_details`.
|
|
57
|
+
- **The tools guide says each thing once and plainly.** Each example is in the
|
|
58
|
+
form the tool mode uses (MCP calls, or commands in CLI mode). There is one
|
|
59
|
+
Rules list, each rule with its reason, and no all-caps emphasis, which Claude
|
|
60
|
+
Code's docs say makes Claude over-apply a rule. Its first rule maps each
|
|
61
|
+
question a file read answers worse (a table's columns, a model's associations,
|
|
62
|
+
an action's filters, a model's tests) to the call that answers it. The tool
|
|
63
|
+
names are listed only in CLI mode, where `tool NAME --help` gives a command's
|
|
64
|
+
parameters, since an MCP client lists its tools itself. The six rules of the
|
|
65
|
+
protocol keep their wording minus the capitals, in the plugin's `rules.md` too.
|
|
66
|
+
- **The root file's app conventions are under `## Conventions`,** apart from
|
|
67
|
+
the tools guide's `### Rules`. The MCP fallback line says `tool --list` lists
|
|
68
|
+
the tools and `tool NAME --help` gives the parameters. A root file an earlier
|
|
69
|
+
run wrote for a tool the record does not name stays planned for, so it is
|
|
70
|
+
kept current instead of read stale beside a second copy.
|
|
71
|
+
- **Each rules file declares one scope** (always, by paths, or on request),
|
|
72
|
+
which one adapter per AI tool writes as `paths:`, `globs:` and `alwaysApply`,
|
|
73
|
+
or `applyTo`.
|
|
74
|
+
|
|
75
|
+
### Fixed
|
|
76
|
+
|
|
77
|
+
- **On prism 1, an initializer that does not parse names the right line** for
|
|
78
|
+
an error that is not about a missing closer (an operator with nothing after
|
|
79
|
+
it named the `configure` line), and the `if` rather than its `elsif` for a
|
|
80
|
+
conditional left open.
|
|
81
|
+
|
|
8
82
|
## [5.38.1] - 2026-10-29
|
|
9
83
|
|
|
10
84
|
### Fixed
|
data/README.md
CHANGED
|
@@ -138,7 +138,7 @@ You catch it, fix it, re-prompt, and something next to it breaks. The tokens are
|
|
|
138
138
|
| **35 read-only tools** | Schema, models, controllers, routes, views, Stimulus, Turbo, jobs, services, mailers, i18n, gems, config, tests, security, performance and more. Every answer comes from your app. |
|
|
139
139
|
| **Answers it can trust** | Models are read with the Prism parser. A model and each scope carry `[VERIFIED]` or `[INFERRED]` (`[STATIC]` without a boot), so the assistant knows what still needs a runtime check. |
|
|
140
140
|
| **Three ways in** | MCP over stdio, MCP mounted in your app over HTTP, or plain CLI in any terminal. |
|
|
141
|
-
| **Context files per AI tool** | `CLAUDE.md`, Cursor rules, Copilot instructions, `AGENTS.md`, each with the MCP config its tool picks up, and six anti-hallucination rules
|
|
141
|
+
| **Context files per AI tool** | `CLAUDE.md`, Cursor rules, Copilot instructions, `AGENTS.md`, each with the MCP config its tool picks up, and six anti-hallucination rules. |
|
|
142
142
|
| **Works on apps that won't boot** | Missing ENV vars, no database, a broken initializer: the tools answer from `config/routes.rb`, the schema dump and the source files, and say so. |
|
|
143
143
|
| **Real app shapes** | Packwerk packs, in-repo engines, multi-database dumps, Mongoid, API-only apps, a folder holding several apps. |
|
|
144
144
|
| **Read-only and careful** | SQL runs read-only with a timeout, a row limit and column redaction. Logs are redacted before they leave the process. Secrets files are never served. |
|
|
@@ -221,7 +221,7 @@ The legacy `rails://models/{name}` form is still accepted. Plus 9 static resourc
|
|
|
221
221
|
|
|
222
222
|
<br>
|
|
223
223
|
|
|
224
|
-
|
|
224
|
+
The root context file carries six rules the assistant reads before writing code, in compact and full mode alike. That file is `AGENTS.md`, which Cursor, OpenCode and Codex read and `CLAUDE.md` imports, or `CLAUDE.md` itself when none of those three is chosen. Copilot reads its own copy in `.github/copilot-instructions.md`. With `generate_root_files` off, the `rails-mcp-tools` rules in `.claude/rules/`, `.cursor/rules/` and `.github/instructions/` carry them instead (Cursor loads its copy on request):
|
|
225
225
|
|
|
226
226
|
1. Verify before you write. Never reference a column, association, route, helper, method, class, partial or gem that a tool call in this turn did not confirm.
|
|
227
227
|
2. Mark every assumption with `[ASSUMPTION]`. "I'd need to check X first" is a good answer.
|
data/docs/ARCHITECTURE.md
CHANGED
|
@@ -41,7 +41,7 @@ graph TD
|
|
|
41
41
|
direction LR
|
|
42
42
|
MCP["MCP Server\nstdio / HTTP\nResources\nVFS URIs"]
|
|
43
43
|
CLI["CLI Runner\nRake / Thor\nSame 35 tools\nNo server needed"]
|
|
44
|
-
S["Serializers\
|
|
44
|
+
S["Serializers\n20 modules\nStatic files\nPer-AI-tool"]
|
|
45
45
|
end
|
|
46
46
|
|
|
47
47
|
style app fill:#4a9eff,stroke:#2d7ad4,color:#fff
|
|
@@ -196,28 +196,30 @@ Result: controller and view tools automatically include relevant schema informat
|
|
|
196
196
|
|
|
197
197
|
### Serializers (`lib/rails_ai_context/serializers/`)
|
|
198
198
|
|
|
199
|
-
|
|
199
|
+
20 modules that format introspection output for different AI tools:
|
|
200
200
|
|
|
201
201
|
| Serializer | Output |
|
|
202
202
|
|:-----------|:-------|
|
|
203
|
-
| `
|
|
203
|
+
| `ContextFileSerializer` | Writes a run's files: the root files the `LoadPlan` picks, each AI tool's rules, and the JSON dump |
|
|
204
|
+
| `LoadPlan` | Which root files the chosen AI tools get and what each holds: the root content, an `@AGENTS.md` import, or nothing, so the content is written once into a file every chosen tool reads (`AiTool#reads`) |
|
|
205
|
+
| `RootFile` | The root context file, the same bytes at every path it lands at (`AGENTS.md`, `CLAUDE.md`, `.github/copilot-instructions.md`): compact, or full through `MarkdownSerializer` |
|
|
204
206
|
| `ClaudeRulesSerializer` | `.claude/rules/*.md` |
|
|
205
|
-
| `CursorRulesSerializer` | `.cursor/rules/*.mdc
|
|
206
|
-
| `CopilotSerializer` | `.github/copilot-instructions.md` |
|
|
207
|
+
| `CursorRulesSerializer` | `.cursor/rules/*.mdc`, and takes the block an earlier release wrote out of `.cursorrules` |
|
|
207
208
|
| `CopilotInstructionsSerializer` | `.github/instructions/*.instructions.md` |
|
|
208
|
-
| `
|
|
209
|
-
| `OpencodeRulesSerializer` | `app/models/AGENTS.md`, `app/controllers/AGENTS.md` |
|
|
209
|
+
| `OpencodeRulesSerializer` | `app/models/AGENTS.md`, `app/controllers/AGENTS.md` (OpenCode and Codex) |
|
|
210
210
|
| `JsonSerializer` | `.ai-context.json` |
|
|
211
|
-
| `MarkdownSerializer` |
|
|
212
|
-
| `
|
|
213
|
-
| `
|
|
214
|
-
| `
|
|
215
|
-
| `
|
|
216
|
-
| `
|
|
211
|
+
| `MarkdownSerializer` | The full-mode root file |
|
|
212
|
+
| `CompactSerializerHelper` | The compact root file's sections |
|
|
213
|
+
| `RuleScope` | When a rules file loads (every session, by path, or on request), written as each AI tool's frontmatter |
|
|
214
|
+
| `Budget` | Every size rule: the bytes per kind of file, the 240-character list line, and how many of each list a file names |
|
|
215
|
+
| `ModelSection` | The model list, rendered once at the density its file takes |
|
|
216
|
+
| `StackSections` | The header, gems, architecture and global before_actions, each rendered once at the density its file takes |
|
|
217
|
+
| `StackOverviewHelper` | Stack overview lines, the test command, and the rule-file write path four serializers share |
|
|
218
|
+
| `ToolGuideHelper` | The tools guide, each example in the one form the tool mode uses |
|
|
219
|
+
| `GuideExamples` | The model, controller and files the guide's examples name, the app's own where it has them |
|
|
217
220
|
| `SectionFacts` | The facts every surface states about an app - auth, assets, associations, the filter chain, an unread entry's row, the static-tier notice - each rendered in one place |
|
|
218
|
-
| `SectionMarkerWriter` | Writes a managed section into a file the user also owns |
|
|
219
|
-
| `
|
|
220
|
-
| `Base` | Holds the context hash a serializer renders |
|
|
221
|
+
| `SectionMarkerWriter` | Writes a managed section into a file the user also owns, and takes one out |
|
|
222
|
+
| `Base` | Holds the context hash a serializer renders, and the run's `LoadPlan` |
|
|
221
223
|
|
|
222
224
|
### CLI (`exe/rails-ai-context`, `lib/rails_ai_context/cli/`)
|
|
223
225
|
|
data/docs/CONFIGURATION.md
CHANGED
|
@@ -87,11 +87,12 @@ empty list wrote every tool's files.
|
|
|
87
87
|
| Option | Type | Default | Description |
|
|
88
88
|
|:-------|:-----|:--------|:------------|
|
|
89
89
|
| `preset` | Symbol | `:full` | `:full` (40 introspectors) or `:standard` (17 introspectors) |
|
|
90
|
-
| `context_mode` | Symbol | `:compact` | `:compact` (
|
|
90
|
+
| `context_mode` | Symbol | `:compact` | `:compact` (the root file within `claude_max_lines` lines and 12,000 bytes) or `:full` (no line cap, all introspection data within 24,000 bytes). Any other value is refused, and so is any other `CONTEXT_MODE` on a rake task |
|
|
91
91
|
| `introspectors` | Array of symbols | (from preset) | Override the introspector list directly |
|
|
92
|
-
| `generate_root_files` | Boolean | `true` | Set `false` to generate split rules only: no CLAUDE.md, AGENTS.md
|
|
92
|
+
| `generate_root_files` | Boolean | `true` | Set `false` to generate split rules only: no CLAUDE.md, AGENTS.md or copilot-instructions.md, and the overview and tools rules are written in their place (`.ai-context.json` is still written) |
|
|
93
93
|
| `anti_hallucination_rules` | Boolean | `true` | Embed 6-rule verification protocol in generated context files |
|
|
94
|
-
| `
|
|
94
|
+
| `report_issue_line` | Boolean | `true` | End every tool answer with one line asking the AI to offer you a GitHub issue when rails-ai-context answered wrong, missed something or failed |
|
|
95
|
+
| `claude_max_lines` | Integer | `150` | Budget for the non-blank lines of the compact root file's gem-managed block, the `<!-- BEGIN/END rails-ai-context -->` markers included, beside its 12,000 bytes. Over budget, the data sections (Stack, Key models, Gems, Architecture) are cut from the bottom, down to none; the title and the Commands, Warnings, Rules and Tools sections are never cut, so they set the smallest file a budget can give (about 70 lines with the anti-hallucination protocol). Must be positive |
|
|
95
96
|
|
|
96
97
|
### MCP Server
|
|
97
98
|
|
|
@@ -296,11 +297,13 @@ Lightweight subset for faster generation:
|
|
|
296
297
|
| AI Tool | Root File | Split Rules | MCP Config |
|
|
297
298
|
|:--------|:----------|:------------|:-----------|
|
|
298
299
|
| Claude Code | `CLAUDE.md` | `.claude/rules/*.md` | `.mcp.json` |
|
|
299
|
-
| Cursor |
|
|
300
|
+
| Cursor | `AGENTS.md` | `.cursor/rules/*.mdc` | `.cursor/mcp.json` |
|
|
300
301
|
| GitHub Copilot | `.github/copilot-instructions.md` | `.github/instructions/*.instructions.md` | `.vscode/mcp.json` |
|
|
301
302
|
| OpenCode | `AGENTS.md` | `app/models/AGENTS.md`, `app/controllers/AGENTS.md` | `opencode.json` |
|
|
302
303
|
| Codex CLI | (shares `AGENTS.md`) | (shares OpenCode rules) | `.codex/config.toml` |
|
|
303
304
|
|
|
305
|
+
The root content is written once, into a file every chosen tool reads: `AGENTS.md` when Cursor, OpenCode or Codex CLI is chosen, with `CLAUDE.md` holding only `@AGENTS.md`, and Copilot's identical copy beside it. With `generate_root_files` off, the Claude Code, Cursor and Copilot rules carry the overview and the tools guide instead. See [Generated Files](GUIDE.md#generated-files).
|
|
306
|
+
|
|
304
307
|
---
|
|
305
308
|
|
|
306
309
|
## Examples
|
data/docs/CUSTOM_TOOLS.md
CHANGED
|
@@ -80,7 +80,7 @@ if defined?(RailsAiContext) && RailsAiContext.respond_to?(:configure)
|
|
|
80
80
|
end
|
|
81
81
|
```
|
|
82
82
|
|
|
83
|
-
Custom tools appear alongside built-in tools in the MCP server and CLI, and in the tool counts
|
|
83
|
+
Custom tools appear alongside built-in tools in the MCP server and CLI, and in the tool counts of the generated context files. In CLI mode the root file's list of commands names them too; in MCP mode the client lists them with their descriptions.
|
|
84
84
|
|
|
85
85
|
Use the class *name* as a string: classes under `app/` (including
|
|
86
86
|
`app/mcp_tools/`) are not autoloadable while initializers run, so a bare
|
data/docs/FAQ.md
CHANGED
|
@@ -65,7 +65,7 @@ Yes. Run `rails-ai-context init` in that folder. It asks once, gives each app it
|
|
|
65
65
|
|
|
66
66
|
**Yes, commit these:**
|
|
67
67
|
- `.mcp.json`, `.cursor/mcp.json`, `.vscode/mcp.json`, `opencode.json` - so teammates get the MCP server after approving it once in their AI tool
|
|
68
|
-
- `CLAUDE.md`, `.claude/rules/`, `.cursor/rules/`, `.
|
|
68
|
+
- `CLAUDE.md`, `.claude/rules/`, `.cursor/rules/`, `.github/copilot-instructions.md`, `.github/instructions/`, `AGENTS.md` - so AI has context
|
|
69
69
|
- `config/initializers/rails_ai_context.rb`, `.rails-ai-context.yml` - so config is shared
|
|
70
70
|
|
|
71
71
|
**Don't commit:**
|
|
@@ -133,8 +133,8 @@ PostgreSQL, MySQL (with MariaDB) and SQLite. Each gets database-specific safety
|
|
|
133
133
|
|
|
134
134
|
### What's `:compact` vs `:full` context mode?
|
|
135
135
|
|
|
136
|
-
- **`:compact`** (default) -
|
|
137
|
-
- **`:full`** - no line cap. All introspection data
|
|
136
|
+
- **`:compact`** (default) - the root file stays within 150 non-blank lines (`claude_max_lines`) and 12,000 bytes, and names the 10 most connected models. The tools answer the rest.
|
|
137
|
+
- **`:full`** - no line cap. All introspection data, within 24,000 bytes, cut from the bottom when it does not fit.
|
|
138
138
|
|
|
139
139
|
### Can I use YAML config with the Gemfile approach?
|
|
140
140
|
|
|
@@ -142,7 +142,7 @@ Yes. The file is applied first and a `configure` block wins only the keys it ass
|
|
|
142
142
|
|
|
143
143
|
### What's `generate_root_files`?
|
|
144
144
|
|
|
145
|
-
When `true` (default), generates the root files:
|
|
145
|
+
When `true` (default), generates the root files the chosen AI tools read: AGENTS.md, CLAUDE.md and copilot-instructions.md. Set to `false` to only generate split rules (.claude/rules/, .cursor/rules/, etc.), which then carry the project overview and the tools guide too. `.ai-context.json` is written either way.
|
|
146
146
|
|
|
147
147
|
---
|
|
148
148
|
|
|
@@ -155,11 +155,13 @@ Depends on your `ai_tools` config. For all tools:
|
|
|
155
155
|
| AI Tool | Files |
|
|
156
156
|
|:--------|:------|
|
|
157
157
|
| Claude | CLAUDE.md, .claude/rules/*.md |
|
|
158
|
-
| Cursor | .cursor/rules/*.mdc
|
|
158
|
+
| Cursor | AGENTS.md, .cursor/rules/*.mdc |
|
|
159
159
|
| Copilot | .github/copilot-instructions.md, .github/instructions/*.instructions.md |
|
|
160
160
|
| OpenCode | AGENTS.md, app/models/AGENTS.md, app/controllers/AGENTS.md |
|
|
161
161
|
| Codex | Shares AGENTS.md and OpenCode rules |
|
|
162
162
|
|
|
163
|
+
The root content is written once, into a file every chosen tool reads. `AGENTS.md` carries it when Cursor, OpenCode or Codex is chosen, and `CLAUDE.md` then holds only `@AGENTS.md`, which Claude Code expands at launch. Copilot keeps an identical copy in `.github/copilot-instructions.md`. `.cursorrules` is no longer written, and a run with root files on takes out the block an earlier release wrote there and keeps your own lines. See [Generated Files](GUIDE.md#generated-files).
|
|
164
|
+
|
|
163
165
|
### How do I regenerate context files?
|
|
164
166
|
|
|
165
167
|
```bash
|
|
@@ -255,13 +257,15 @@ Check that your Rails app boots (`rails runner "puts 'ok'"`) and that schema/mod
|
|
|
255
257
|
|
|
256
258
|
### Context files are too large
|
|
257
259
|
|
|
258
|
-
Use compact mode (default)
|
|
260
|
+
Use compact mode (default), and lower `claude_max_lines` for a shorter root file:
|
|
259
261
|
|
|
260
262
|
```ruby
|
|
261
263
|
config.context_mode = :compact
|
|
262
|
-
config.
|
|
264
|
+
config.claude_max_lines = 100
|
|
263
265
|
```
|
|
264
266
|
|
|
267
|
+
Every file already has a byte budget ([Generated Files](GUIDE.md#generated-files)). Turning root files off does not shrink what Claude Code and Copilot load: the overview and the whole tools guide move into rules files they load in every session.
|
|
268
|
+
|
|
265
269
|
---
|
|
266
270
|
|
|
267
271
|
<div align="center" markdown="1">
|
data/docs/GUIDE.md
CHANGED
|
@@ -97,7 +97,7 @@ No Gemfile entry, no initializer, no files in your project besides config and co
|
|
|
97
97
|
|
|
98
98
|
```
|
|
99
99
|
1. Claude Code -> CLAUDE.md + .claude/rules/
|
|
100
|
-
2. Cursor -> .cursor/rules/
|
|
100
|
+
2. Cursor -> AGENTS.md + .cursor/rules/
|
|
101
101
|
3. GitHub Copilot -> .github/copilot-instructions.md + .github/instructions/
|
|
102
102
|
4. OpenCode -> AGENTS.md
|
|
103
103
|
5. Codex CLI -> AGENTS.md + .codex/config.toml
|
|
@@ -120,7 +120,7 @@ No Gemfile entry, no initializer, no files in your project besides config and co
|
|
|
120
120
|
6. **Writes `.rails-ai-context.yml`** with `ai_tools`, `tool_mode` and `context_files`. Only a key whose value changed is rewritten, where it stands; your comments and other keys are kept, and a run that changes no value leaves the file as it was.
|
|
121
121
|
7. **Adds lines to `.gitignore`**, if the file exists: `.ai-context.json` (not for choice 3) and `.codex/config.toml` (always, because it holds this machine's Ruby paths). A line that is already there is not added again.
|
|
122
122
|
8. **Asks about a pre-commit hook:** `Install a pre-commit hook that checks staged Ruby, ERB and JavaScript files for syntax errors? (y/N)`. Only `y` installs it. The hook runs `bundle exec rails-ai-context tool validate` (`rails-ai-context tool validate` in a standalone install) on the staged `.rb`, `.erb`, `.js`, `.mjs` and `.cjs` files and stops a commit whose files do not parse (JavaScript is parsed by `node`, as [`rails_validate`](TOOLS.md#rails_validate) describes); the Rails-reference checks (`level=rails`) are left to the tool, as Brakeman would slow every commit. An app that cannot boot (an initializer that needs a variable the shell lacks, say) is still checked, from its source, and the hook shows why it did not boot; it shows whatever else the check prints to stderr too, so a check that cannot run says why. Every staged name is read whole, one with characters outside ASCII included; a name holding a comma, which the files list cannot carry, is named and left unchecked. It goes where git runs hooks (`git rev-parse --git-path hooks`), so an app checked out as a submodule, an app inside a monorepo and a repo with `core.hooksPath` set all get it where git will run it. The hook names the apps it covers and validates each one's staged files (deleted ones aside) from inside that app; installing in a second app of the same monorepo adds it to the hook, unless the hook was changed by hand, which it says, and for an app below the top of the repository the question names the repository. A hook an earlier version wrote, and nobody changed since, is brought up to date without asking again: the oldest handed validate the files a commit deletes too, and the commit failed on them, and later ones ran `rails 'ai:tool[validate]'`, which has to boot the app, with its errors thrown away, so an app that could not boot failed every commit with no reason given. Any other hook that runs `rails-ai-context` - one changed by hand, or a team's own that calls it among other checks - is left as it is, with a message. No hook is offered for an app the repository does not track yet (an app under a dotfiles repository at `$HOME`, say), nor into a `core.hooksPath` outside the repository, which every repository using it shares; both say why. No question is asked outside a git repository or when the hook already covers the app. When another `pre-commit` hook exists there it prints `Skipped pre-commit hook (existing hook found - add manually)` and moves on.
|
|
123
|
-
9. **Generates the context files** for the selected tools. Skipped for choice 3. If files that v5.0.0 stopped generating are still there (`.claude/rules/rails-ui-patterns.md`, `.claude/rules/rails-accessibility.md`, `.cursor/rules/rails-ui-patterns.mdc`, `.github/instructions/rails-ui-patterns.instructions.md`), it lists them first and asks `Delete them? [y/N]:`. Without a terminal, or under `--defaults`, it prints the `rm` command and does not ask; under `--prune` it deletes them without asking.
|
|
123
|
+
9. **Generates the context files** for the selected tools. Skipped for choice 3. If files that v5.0.0 stopped generating are still there (`.claude/rules/rails-ui-patterns.md`, `.claude/rules/rails-accessibility.md`, `.cursor/rules/rails-ui-patterns.mdc`, `.github/instructions/rails-ui-patterns.instructions.md`), it lists them first and asks `Delete them? [y/N]:`. Without a terminal, or under `--defaults`, it prints the `rm` command and does not ask; under `--prune` it deletes them without asking. Files an earlier run wrote that this run no longer writes go without a question, and the output names them: the block in `.cursorrules`, and an overview or tools rule the root file states ([Generated Files](#generated-files)).
|
|
124
124
|
10. **Prints a summary:** the files each selected tool got, the commands to run next, and, in the MCP setup, each tool's next step: the approval or trust step that tool asks for before it starts a project's MCP server (approve the server in Claude Code, turn it on in Cursor, trust the folder in VS Code and Codex CLI, restart OpenCode).
|
|
125
125
|
|
|
126
126
|
Every question has a flag, so an AI tool or a script can run the install to the end with nobody at the keyboard (the [copy-paste prompts](PROMPTS.md) are built on them):
|
|
@@ -173,11 +173,18 @@ The gem has two context modes that control how much data goes into the generated
|
|
|
173
173
|
rails ai:context
|
|
174
174
|
```
|
|
175
175
|
|
|
176
|
-
-
|
|
177
|
-
|
|
178
|
-
|
|
179
|
-
|
|
180
|
-
|
|
176
|
+
- The root file (AGENTS.md, CLAUDE.md or copilot-instructions.md) stays within
|
|
177
|
+
12,000 bytes and `claude_max_lines` (150) non-blank lines. Over budget, the
|
|
178
|
+
data sections are cut from the bottom; the title and the Commands, Warnings,
|
|
179
|
+
Rules and Tools sections are never cut, so a budget smaller than they are
|
|
180
|
+
(about 70 lines) leaves just them
|
|
181
|
+
- It names the 10 most connected models. A list names what fits a 240-character
|
|
182
|
+
line and ends with "...N more"; the tools answer the rest
|
|
183
|
+
- It holds a project overview and the tools guide. The guide gives each example
|
|
184
|
+
in the one form the tool mode uses (an MCP call, or a command in `:cli` mode)
|
|
185
|
+
and has one Rules list with no ALL-CAPS emphasis, since Claude Code's docs say
|
|
186
|
+
piled-on emphasis makes Claude over-apply a rule. It lists the tool names only
|
|
187
|
+
in `:cli` mode: an MCP client lists the tools itself
|
|
181
188
|
- AI uses MCP tools for detailed data on-demand
|
|
182
189
|
- **Best for:** all apps, especially large ones (30+ models)
|
|
183
190
|
|
|
@@ -189,22 +196,24 @@ rails ai:context:full
|
|
|
189
196
|
CONTEXT_MODE=full rails ai:context
|
|
190
197
|
```
|
|
191
198
|
|
|
192
|
-
-
|
|
193
|
-
-
|
|
199
|
+
- Puts the whole introspection into the root file: every table with its column types, defaults, indexes and foreign keys; every model with its associations, validations, scopes, callbacks, enum values and constants; the app's own routes (the framework's are counted, not listed); Stimulus controllers; and the rest of the introspection. The rules files are the same in both modes
|
|
200
|
+
- The file stays within 24,000 bytes. A large app's data sections are cut from the bottom, with a note that the tools answer the rest; the header, the rules, the tools guide and the last line are never cut
|
|
201
|
+
- The root file ends with the same tools guide and anti-hallucination protocol the compact file carries, so OpenCode and Codex, which read AGENTS.md alone, get them too
|
|
194
202
|
- A plain `rails ai:context` writes compact files again unless `config.context_mode` is `:full`, so each file's last line names the command that keeps full mode: `CONTEXT_MODE=full rails ai:context`, or for a standalone install `rails-ai-context context`, which reads `context_mode` from `.rails-ai-context.yml`
|
|
195
|
-
-
|
|
196
|
-
- **Best for:** small apps (<30 models) where the full dump fits in context
|
|
203
|
+
- **Best for:** small apps (<30 models), whose full dump fits the budget
|
|
197
204
|
|
|
198
205
|
### Per-format with mode override
|
|
199
206
|
|
|
200
207
|
```bash
|
|
201
|
-
# Full dump
|
|
208
|
+
# Full dump in the root file Claude Code reads
|
|
202
209
|
CONTEXT_MODE=full rails ai:context:claude
|
|
203
210
|
|
|
204
211
|
# Full dump for Copilot only
|
|
205
212
|
CONTEXT_MODE=full rails ai:context:copilot
|
|
206
213
|
```
|
|
207
214
|
|
|
215
|
+
Where `CLAUDE.md` imports `AGENTS.md`, the first command writes the full dump into `AGENTS.md`, which Cursor, OpenCode and Codex read too.
|
|
216
|
+
|
|
208
217
|
### Set mode in configuration
|
|
209
218
|
|
|
210
219
|
```ruby
|
|
@@ -220,26 +229,32 @@ end
|
|
|
220
229
|
|
|
221
230
|
## Generated Files
|
|
222
231
|
|
|
223
|
-
`rails ai:context` generates **
|
|
232
|
+
`rails ai:context` generates **19 files** across all AI assistants. No run writes all of them: the three root files are written while `generate_root_files` is on (the default), and the six overview and tools rules only when it is off, since the root file states them otherwise.
|
|
233
|
+
|
|
234
|
+
The root content is written once, into a file every chosen AI tool reads. `AGENTS.md` carries it when Cursor, OpenCode or Codex is chosen: Cursor reads `AGENTS.md` and `CLAUDE.md` as it reads its own always-on rules ([Cursor](https://cursor.com/help/customization/rules#how-does-claudemd-work-in-cursor)). `CLAUDE.md` then holds only `@AGENTS.md`, an import Claude Code expands at launch ([Claude Code](https://code.claude.com/docs/en/memory#import-additional-files)); without those three, `CLAUDE.md` carries the content itself. `.github/copilot-instructions.md` gets an identical copy, since github.com chat, Visual Studio, JetBrains, Xcode and code review read no other file ([GitHub](https://docs.github.com/en/copilot/reference/custom-instructions-support)), and Copilot CLI drops identical copies.
|
|
235
|
+
|
|
236
|
+
Every file has a byte budget: 12,000 bytes for a compact root file, 24,000 in full mode, 8,000 for a rule file, and 12,000 for a tools rule that stands in for the root file. It is low on purpose, since these files share the agent's context with your own instructions, and Codex reads at most 32 KiB of project docs in all. A list names what fits a 240-character line and ends with "...N more"; the tools answer the rest.
|
|
224
237
|
|
|
225
|
-
A file whose section has nothing in it is not written. An app with no models gets no `.claude/rules/rails-models.md`, and every surface names the file and the reason so a deliberate omission is not mistaken for a failed run. `rails ai:context` and the installer print `➖ .claude/rules/rails-models.md (no models)`; the CLI and the watcher print `Not applicable: .claude/rules/rails-models.md (no models)`.
|
|
238
|
+
A file whose section has nothing in it is not written. An app with no models gets no `.claude/rules/rails-models.md`, and every surface names the file and the reason so a deliberate omission is not mistaken for a failed run. `rails ai:context` and the installer print `➖ .claude/rules/rails-models.md (no models)`; the CLI and the watcher print `Not applicable: .claude/rules/rails-models.md (no models)`. A rule the root file states is named the same way, with the reason `in the root file`.
|
|
239
|
+
|
|
240
|
+
A run removes the files an earlier run wrote that it no longer writes. The CLI and the watcher print `Removed: PATH`, or `Removed the generated block from PATH` where your own lines stay; `rails ai:context` and the installer mark it `(removed)` or `(generated block removed)`. `doctor` counts a file a run would remove as out of date.
|
|
226
241
|
|
|
227
242
|
### Claude Code (6 files)
|
|
228
243
|
|
|
229
244
|
| File | Purpose | Notes |
|
|
230
245
|
|------|---------|-------|
|
|
231
|
-
| `CLAUDE.md` |
|
|
232
|
-
| `.claude/rules/rails-schema.md` | Database table listing | Every database's tables, each database under its own heading when the app has more than one. A database of Solid Queue, Solid Cache or Solid Cable tables only, as Rails 8's queue, cache and cable are, is named in
|
|
233
|
-
| `.claude/rules/rails-models.md` | Model listing with associations |
|
|
234
|
-
| `.claude/rules/rails-context.md` | Project
|
|
235
|
-
| `.claude/rules/rails-mcp-tools.md` |
|
|
236
|
-
| `.claude/rules/rails-components.md` | View component listing | Written only when the app has view components. |
|
|
246
|
+
| `CLAUDE.md` | Root context file | Holds only `@AGENTS.md` where `AGENTS.md` carries the root content, and the content itself otherwise. Claude Code reads it at launch. |
|
|
247
|
+
| `.claude/rules/rails-schema.md` | Database table listing | Every database's tables, each database under its own heading when the app has more than one. A database of Solid Queue, Solid Cache or Solid Cable tables only, as Rails 8's queue, cache and cable are, is named in the root file instead (`queue: Solid Queue (13 tables)`). Loaded when Claude Code opens a schema dump or a migration. |
|
|
248
|
+
| `.claude/rules/rails-models.md` | Model listing with associations | Loaded when Claude Code opens a file in `app/models/`. |
|
|
249
|
+
| `.claude/rules/rails-context.md` | Project overview | Written only with `generate_root_files` off. Loaded in every session. |
|
|
250
|
+
| `.claude/rules/rails-mcp-tools.md` | Tools guide | Written only with `generate_root_files` off. Loaded in every session: the protocol, the workflows and the rules, as the root file carries them. |
|
|
251
|
+
| `.claude/rules/rails-components.md` | View component listing | Written only when the app has view components. Loaded when Claude Code opens a file in `app/components/` or `app/views/components/`. |
|
|
237
252
|
|
|
238
253
|
### OpenCode (3 files)
|
|
239
254
|
|
|
240
255
|
| File | Purpose | Notes |
|
|
241
256
|
|------|---------|-------|
|
|
242
|
-
| `AGENTS.md` |
|
|
257
|
+
| `AGENTS.md` | Root context file | Carries the root content for OpenCode, Codex and Cursor, and for Claude Code through the import in `CLAUDE.md`. OpenCode reads CLAUDE.md only where there is no AGENTS.md. |
|
|
243
258
|
| `app/models/AGENTS.md` | Model reference | Auto-loaded by OpenCode when reading files in `app/models/`. One you wrote yourself keeps its text, with the listing added between markers. |
|
|
244
259
|
| `app/controllers/AGENTS.md` | Controller reference | Auto-loaded by OpenCode when reading files in `app/controllers/`. One you wrote yourself keeps its text, with the listing added between markers. |
|
|
245
260
|
|
|
@@ -247,21 +262,23 @@ A file whose section has nothing in it is not written. An app with no models get
|
|
|
247
262
|
|
|
248
263
|
| File | Purpose | Notes |
|
|
249
264
|
|------|---------|-------|
|
|
250
|
-
|
|
|
265
|
+
| `AGENTS.md` | Root context file | The file OpenCode and Codex read too. Cursor reads it, and `CLAUDE.md`, like an always-on rule. |
|
|
266
|
+
| `.cursor/rules/rails-project.mdc` | Project overview | `alwaysApply: true` - loaded in every conversation. Written only with `generate_root_files` off. |
|
|
251
267
|
| `.cursor/rules/rails-models.mdc` | Model reference | `globs: app/models/**/*.rb` - auto-attaches when editing models. |
|
|
252
268
|
| `.cursor/rules/rails-controllers.mdc` | Controller reference | `globs: app/controllers/**/*.rb` - auto-attaches when editing controllers. |
|
|
253
|
-
| `.cursor/rules/rails-mcp-tools.mdc` |
|
|
254
|
-
|
|
269
|
+
| `.cursor/rules/rails-mcp-tools.mdc` | Tools guide | `alwaysApply: false` - agent-requested when relevant. Written only with `generate_root_files` off. |
|
|
270
|
+
|
|
271
|
+
`.cursorrules` is no longer written: Cursor calls it legacy, and reads the content from `AGENTS.md`. With root files on, a run takes out the block an earlier release wrote there and keeps your own lines; a file that held only the block is deleted. Cleanup and `doctor` still know the file.
|
|
255
272
|
|
|
256
273
|
### GitHub Copilot (5 files)
|
|
257
274
|
|
|
258
275
|
| File | Purpose | Notes |
|
|
259
276
|
|------|---------|-------|
|
|
260
|
-
| `.github/copilot-instructions.md` |
|
|
277
|
+
| `.github/copilot-instructions.md` | Root context file | An identical copy where `AGENTS.md` or `CLAUDE.md` carries the root content too, since github.com chat, Visual Studio, JetBrains, Xcode and code review read no other file. |
|
|
261
278
|
| `.github/instructions/rails-models.instructions.md` | Model context | `applyTo: app/models/**/*.rb` - loaded when editing models. |
|
|
262
279
|
| `.github/instructions/rails-controllers.instructions.md` | Controller context | `applyTo: app/controllers/**/*.rb` - loaded when editing controllers. |
|
|
263
|
-
| `.github/instructions/rails-context.instructions.md` | Project
|
|
264
|
-
| `.github/instructions/rails-mcp-tools.instructions.md` |
|
|
280
|
+
| `.github/instructions/rails-context.instructions.md` | Project overview | `applyTo: **/*` - loaded everywhere. Written only with `generate_root_files` off. |
|
|
281
|
+
| `.github/instructions/rails-mcp-tools.instructions.md` | Tools guide | `applyTo: **/*` - loaded everywhere but code review. Written only with `generate_root_files` off. |
|
|
265
282
|
|
|
266
283
|
### Generic (1 file)
|
|
267
284
|
|
|
@@ -290,19 +307,19 @@ unmarked file was generated with the app running.
|
|
|
290
307
|
|
|
291
308
|
| Command | Mode | Format | Description |
|
|
292
309
|
|---------|------|--------|-------------|
|
|
293
|
-
| `rails ai:context` | compact | all | Generate all
|
|
310
|
+
| `rails ai:context` | compact | all | Generate all 19 context files |
|
|
294
311
|
| `rails ai:context:full` | full | all | Generate all files in full mode |
|
|
295
|
-
| `rails ai:context:claude` | compact | Claude | CLAUDE.md + .claude/rules
|
|
312
|
+
| `rails ai:context:claude` | compact | Claude | CLAUDE.md + .claude/rules/, and the AGENTS.md it imports when Cursor, OpenCode or Codex is selected too |
|
|
296
313
|
| `rails ai:context:opencode` | compact | OpenCode | AGENTS.md + per-directory AGENTS.md |
|
|
297
314
|
| `rails ai:context:codex` | compact | Codex | AGENTS.md + per-directory AGENTS.md (same files as OpenCode), and `.codex/config.toml` in MCP mode |
|
|
298
|
-
| `rails ai:context:cursor` | compact | Cursor | .cursor/rules/ |
|
|
315
|
+
| `rails ai:context:cursor` | compact | Cursor | AGENTS.md + .cursor/rules/ |
|
|
299
316
|
| `rails ai:context:copilot` | compact | Copilot | copilot-instructions.md + .github/instructions/ |
|
|
300
317
|
| `rails ai:context:json` | - | JSON | .ai-context.json |
|
|
301
|
-
| `CONTEXT_MODE=full rails ai:context:claude` | full | Claude | Full dump
|
|
302
|
-
| `CONTEXT_MODE=full rails ai:context:opencode` | full | OpenCode | Full dump in AGENTS.md, which Codex
|
|
318
|
+
| `CONTEXT_MODE=full rails ai:context:claude` | full | Claude | Full dump in the root file Claude Code reads |
|
|
319
|
+
| `CONTEXT_MODE=full rails ai:context:opencode` | full | OpenCode | Full dump in AGENTS.md, which Codex and Cursor read too |
|
|
303
320
|
| `CONTEXT_MODE=full rails ai:context:copilot` | full | Copilot | Full dump for Copilot only |
|
|
304
321
|
|
|
305
|
-
|
|
322
|
+
The rules files are the same in both modes, so `CONTEXT_MODE=full` changes only the root file.
|
|
306
323
|
|
|
307
324
|
Each `rails ai:context:<tool>` adds its tool to the recorded selection and, in MCP mode, writes that tool's MCP config too (`.cursor/mcp.json` for Cursor), since its files tell the AI to call the MCP tools.
|
|
308
325
|
|
|
@@ -430,10 +447,10 @@ if defined?(RailsAiContext) && RailsAiContext.respond_to?(:configure)
|
|
|
430
447
|
end
|
|
431
448
|
```
|
|
432
449
|
|
|
433
|
-
- **`:mcp`** - context files show MCP tool syntax (e.g. `rails_get_schema(table: "users")`). CLI
|
|
434
|
-
- **`:cli`** - context files show CLI syntax (e.g. `rails 'ai:tool[schema]' table=users`). No MCP server required. Every file follows it: the root files, the split rule files and OpenCode's per-directory `AGENTS.md`, whose tools rule files then describe the CLI tools.
|
|
450
|
+
- **`:mcp`** - context files show MCP tool syntax (e.g. `rails_get_schema(table: "users")`), each example in that form alone. The root file names the CLI fallback once and lists no tool names, since the MCP client lists the tools itself.
|
|
451
|
+
- **`:cli`** - context files show CLI syntax (e.g. `rails 'ai:tool[schema]' table=users`). No MCP server required. Every file follows it: the root files, the split rule files and OpenCode's per-directory `AGENTS.md`, whose tools rule files then describe the CLI tools. The root file lists the tool names, since nothing else does.
|
|
435
452
|
|
|
436
|
-
Every tool count and list in the generated files is the set the server serves: the built-in tools `skip_tools` leaves, plus `custom_tools`.
|
|
453
|
+
Every tool count and list in the generated files is the set the server serves: the built-in tools `skip_tools` leaves, plus `custom_tools`. In CLI mode the root file's list of commands names a custom tool too; in MCP mode the client lists every tool itself. A workflow step, rule or pointer whose tool is skipped is left out, or said without the tool (with `rails_get_context` skipped, the model workflow starts from `rails_get_model_details`), so no file sends the AI to a tool the server does not serve.
|
|
437
454
|
|
|
438
455
|
The workflow examples name the app's own most connected model, one of its controllers, a template and a partial it renders. An app with none of one gets an obvious placeholder (`YourModel`, `shared/your_partial`) rather than a name that reads like the app's.
|
|
439
456
|
|
|
@@ -1296,7 +1313,7 @@ if defined?(RailsAiContext) && RailsAiContext.respond_to?(:configure)
|
|
|
1296
1313
|
# Context mode: :compact (default) or :full
|
|
1297
1314
|
config.context_mode = :compact
|
|
1298
1315
|
|
|
1299
|
-
# Max lines for
|
|
1316
|
+
# Max non-blank lines for the root file in compact mode
|
|
1300
1317
|
config.claude_max_lines = 150
|
|
1301
1318
|
|
|
1302
1319
|
# Output directory for context files (default: Rails.root)
|
|
@@ -1410,7 +1427,7 @@ end
|
|
|
1410
1427
|
| `preset` | Symbol | `:full` | Introspector preset (`:full` or `:standard`) |
|
|
1411
1428
|
| `introspectors` | Array | 40 (full preset) | Which introspectors to run |
|
|
1412
1429
|
| `context_mode` | Symbol | `:compact` | `:compact` or `:full` |
|
|
1413
|
-
| `claude_max_lines` | Integer | `150` | Budget for the non-blank lines of
|
|
1430
|
+
| `claude_max_lines` | Integer | `150` | Budget for the non-blank lines of the compact root file's gem-managed block, the `<!-- BEGIN/END rails-ai-context -->` markers included, beside its 12,000 bytes. Over budget, the data sections (Stack, Key models, Gems, Architecture) are cut from the bottom, down to none; the title and the Commands, Warnings, Rules and Tools sections are never cut, so they set the smallest file a budget can give (about 70 lines with the anti-hallucination protocol) |
|
|
1414
1431
|
| `max_tool_response_chars` | Integer | `200_000` | Safety cap for MCP tool responses and resource payloads |
|
|
1415
1432
|
| `cache_ttl` | Integer | `60` | Cache TTL in seconds for introspection results |
|
|
1416
1433
|
| `custom_tools` | Array | `[]` | Additional MCP tool classes to register alongside built-in tools |
|
|
@@ -1430,8 +1447,9 @@ end
|
|
|
1430
1447
|
| `live_reload_debounce` | Float | `1.5` | Debounce interval in seconds for live reload |
|
|
1431
1448
|
| `server_name` | String | `"rails-ai-context"` | The MCP server name the server announces. When it is left at the default, the `RAILS_AI_CONTEXT_SERVER_NAME` environment variable takes its place for one process, which is how a workspace's entries announce their app |
|
|
1432
1449
|
| `server_version` | String | gem version | MCP server version. Read-only, there is no setter |
|
|
1433
|
-
| `generate_root_files` | Boolean | `true` | Set `false` to generate split rules only: no CLAUDE.md, AGENTS.md
|
|
1450
|
+
| `generate_root_files` | Boolean | `true` | Set `false` to generate split rules only: no CLAUDE.md, AGENTS.md or copilot-instructions.md, and the overview and tools rules are written in their place (`.ai-context.json` is still written) |
|
|
1434
1451
|
| `anti_hallucination_rules` | Boolean | `true` | Embed 6-rule Anti-Hallucination Protocol in generated context files - set `false` to skip |
|
|
1452
|
+
| `report_issue_line` | Boolean | `true` | End every tool answer with one line asking the AI to offer you a GitHub issue when rails-ai-context answered wrong - set `false` to leave it out |
|
|
1435
1453
|
| `hydration_enabled` | Boolean | `true` | Inject schema hints into controller/view tool responses |
|
|
1436
1454
|
| `hydration_max_hints` | Integer | `5` | Max schema hints per tool response |
|
|
1437
1455
|
| `max_file_size` | Integer | `5_000_000` | Per-file read limit for tools (5MB) |
|
|
@@ -1476,7 +1494,7 @@ if defined?(RailsAiContext) && RailsAiContext.respond_to?(:configure)
|
|
|
1476
1494
|
end
|
|
1477
1495
|
```
|
|
1478
1496
|
|
|
1479
|
-
|
|
1497
|
+
With root files off, the Claude Code, Cursor and Copilot rule sets each get an app overview (`rails-context.md`, `rails-project.mdc`, `rails-context.instructions.md`) and the tools guide (`rails-mcp-tools.md`, `rails-mcp-tools.mdc`, `rails-mcp-tools.instructions.md`) in the root file's place; Cursor loads its guide on request. With root files on, a run removes those six, since the root file states them. OpenCode and Codex have no overview outside AGENTS.md: their split files hold only the model and controller listings.
|
|
1480
1498
|
|
|
1481
1499
|
---
|
|
1482
1500
|
|
|
@@ -1562,8 +1580,8 @@ config.introspectors = %i[schema models routes gems auth api]
|
|
|
1562
1580
|
**Auto-discovery:** Reads `.mcp.json` when a session starts in the folder, and asks you to approve the `rails-ai-context` server once (`claude mcp reset-project-choices` asks again).
|
|
1563
1581
|
|
|
1564
1582
|
**Context files loaded:**
|
|
1565
|
-
- `CLAUDE.md` - read at conversation start
|
|
1566
|
-
- `.claude/rules/*.md` -
|
|
1583
|
+
- `CLAUDE.md` - read at conversation start. Where it holds `@AGENTS.md`, Claude Code expands the import and reads `AGENTS.md` with it
|
|
1584
|
+
- `.claude/rules/*.md` - the schema, models and components rules load when Claude Code opens a file their `paths:` frontmatter matches; the overview and tools rules, written only with `generate_root_files` off, load in every session
|
|
1567
1585
|
|
|
1568
1586
|
**MCP tools:** Available once the server is approved. `/mcp` lists it.
|
|
1569
1587
|
|
|
@@ -1572,14 +1590,15 @@ config.introspectors = %i[schema models routes gems auth api]
|
|
|
1572
1590
|
**Auto-discovery:** Reads `.cursor/mcp.json`. Restart Cursor after the install, and turn `rails-ai-context` on under MCP in Customize if it is off.
|
|
1573
1591
|
|
|
1574
1592
|
**Context files loaded:**
|
|
1593
|
+
- `AGENTS.md` and `CLAUDE.md` - read like an always-on rule, so the root content reaches Cursor from `AGENTS.md`
|
|
1575
1594
|
- `.cursor/rules/*.mdc` - loaded based on `alwaysApply` and `globs` settings
|
|
1576
1595
|
|
|
1577
1596
|
**MDC rule activation modes:**
|
|
1578
1597
|
| Mode | When it activates |
|
|
1579
1598
|
|------|-------------------|
|
|
1580
|
-
| `alwaysApply: true` | Every conversation (project overview) |
|
|
1599
|
+
| `alwaysApply: true` | Every conversation (project overview, root files off) |
|
|
1581
1600
|
| `globs: ["app/models/**/*.rb"]` | When editing files matching the glob pattern |
|
|
1582
|
-
| `alwaysApply: false` + `description` | Agent-requested - loaded when AI decides it's relevant (
|
|
1601
|
+
| `alwaysApply: false` + `description` | Agent-requested - loaded when AI decides it's relevant (tools guide, root files off) |
|
|
1583
1602
|
|
|
1584
1603
|
### OpenCode
|
|
1585
1604
|
|
|
@@ -1624,7 +1643,7 @@ OpenCode uses **per-directory lazy-loading**: when the agent reads a file, it wa
|
|
|
1624
1643
|
**Auto-discovery:** `.vscode/mcp.json` is auto-generated by the install generator.
|
|
1625
1644
|
|
|
1626
1645
|
**Context files loaded:**
|
|
1627
|
-
- `.github/copilot-instructions.md` - repo-wide instructions
|
|
1646
|
+
- `.github/copilot-instructions.md` - repo-wide instructions, the root content. github.com chat, Visual Studio, JetBrains, Xcode and code review read no other root file
|
|
1628
1647
|
- `.github/instructions/*.instructions.md` - path-specific, activated by `applyTo` glob (with `name:` and `description:` frontmatter)
|
|
1629
1648
|
|
|
1630
1649
|
**applyTo patterns:**
|
|
@@ -1632,7 +1651,7 @@ OpenCode uses **per-directory lazy-loading**: when the agent reads a file, it wa
|
|
|
1632
1651
|
|---------|-------------------|
|
|
1633
1652
|
| `app/models/**/*.rb` | Editing model files |
|
|
1634
1653
|
| `app/controllers/**/*.rb` | Editing controller files |
|
|
1635
|
-
| `**/*` | All files (
|
|
1654
|
+
| `**/*` | All files (project overview and tools guide, root files off) |
|
|
1636
1655
|
|
|
1637
1656
|
### Codex CLI
|
|
1638
1657
|
|
data/docs/PROMPTS.md
CHANGED
|
@@ -147,7 +147,7 @@ Set up rails-ai-context for me only in this Rails app: nothing it writes may sho
|
|
|
147
147
|
2. Pick TOOL, the key for the AI tool you are: claude (Claude Code), cursor (Cursor), copilot (GitHub Copilot in VS Code), opencode (OpenCode), codex (Codex CLI). If you are another AI tool, stop and tell me to use the "Another MCP client" prompt instead.
|
|
148
148
|
3. Run `git status --porcelain` and remember its output.
|
|
149
149
|
4. Run `gem install rails-ai-context -v '>= 5.35.0'`, then `rails-ai-context init --tools TOOL --defaults`.
|
|
150
|
-
5. Run `git status --porcelain --untracked-files=all` again. Restore every tracked file that now shows as modified and did not in step 3 with `git checkout -- PATH` (.gitignore is one when the repo has it). If one of them is a context file the repo already had (CLAUDE.md, AGENTS.md, .cursorrules or .github/copilot-instructions.md), also add the line `generate_root_files: false` to .rails-ai-context.yml and run `rails-ai-context context`: the gem then writes its rules into its own rules files instead of that one. Then run `git status --porcelain --untracked-files=all` once more (restoring .gitignore makes files it ignored show up) and add every path that is new compared with step 3 to .git/info/exclude, one per line (create the file if it is missing).
|
|
150
|
+
5. Run `git status --porcelain --untracked-files=all` again. Restore every tracked file that now shows as modified or deleted and did not in step 3 with `git checkout -- PATH` (.gitignore is one when the repo has it). If one of them is a context file the repo already had (CLAUDE.md, AGENTS.md, .cursorrules or .github/copilot-instructions.md), also add the line `generate_root_files: false` to .rails-ai-context.yml and run `rails-ai-context context`: the gem then writes its rules into its own rules files instead of that one. Then run `git status --porcelain --untracked-files=all` once more (restoring .gitignore makes files it ignored show up) and add every path that is new compared with step 3 to .git/info/exclude, one per line (create the file if it is missing).
|
|
151
151
|
6. Run `git status --porcelain` once more and confirm it matches step 3.
|
|
152
152
|
7. Tell me the "Next step" lines the install printed for TOOL, word for word.
|
|
153
153
|
```
|
data/docs/QUICKSTART.md
CHANGED
|
@@ -80,7 +80,7 @@ The install generator created:
|
|
|
80
80
|
| File | Purpose |
|
|
81
81
|
|:-----|:--------|
|
|
82
82
|
| `.mcp.json` / `.cursor/mcp.json` / `.vscode/mcp.json` / `opencode.json` / `.codex/config.toml` | Each AI tool finds its config when it opens the project, then asks you to approve the server once |
|
|
83
|
-
| `CLAUDE.md` + `.claude/rules/` / `.cursor/rules/`
|
|
83
|
+
| `CLAUDE.md` + `.claude/rules/` / `AGENTS.md` + `.cursor/rules/` / `.github/copilot-instructions.md` + `.github/instructions/` | Static context rules your AI reads |
|
|
84
84
|
| `.ai-context.json` | The same context as JSON (added to `.gitignore`) |
|
|
85
85
|
| `config/initializers/rails_ai_context.rb` | All configuration options |
|
|
86
86
|
| `.rails-ai-context.yml` | Your tool selection, and the config file for standalone mode |
|