Module: RailsAiBridge::Serializers::SharedAssistantGuidance

Defined in:
lib/rails_ai_bridge/serializers/shared_assistant_guidance.rb

Overview

Shared high-signal copy for Copilot, Codex, Cursor, and legacy .cursorrules compact output.

See Also:

Constant Summary collapse

OMIT_MERGE_FIRST_LINE =

First line of +overrides.md+ while in stub mode — file is not merged until removed.

/\A<!--\s*rails-ai-bridge:omit-merge\s*-->\z/i

Class Method Summary collapse

Class Method Details

Full-mode Claude Code footer (plain-language bullets; not the compact rules list).

Parameters:

  • context (Hash) —

    introspection context (+:conventions+ optional for architecture line)

Returns:

  • (Array<String>) —

    markdown lines (join with newlines for a string)



156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
 
# File 'lib/rails_ai_bridge/serializers/shared_assistant_guidance.rb', line 156

def claude_full_footer_lines(context)
  arch = context.dig(:conventions, :architecture)
  arch_summary = arch&.any? ? arch.join(', ') : nil

  lines = [
    '## Behavioral Rules',
    '',
    'When working in this codebase:',
    '- Follow existing patterns and conventions detected above',
    '- Use the database schema as the source of truth for column names and types',
    '- Respect existing associations and validations when modifying models'
  ]
  lines << "- Match the project's architecture style (#{arch_summary})" if arch_summary
  lines << "- Run `#{ContextSummary.test_command(context)}` after making changes to verify correctness"
  lines.concat(RegenerationFooter.continuation_lines(command: 'rails ai:bridge', variant: :context_file))
  lines
end

.compact_engineering_rules_footer_lines(context, rules_heading: '## Rules') ⇒ Array<String>

Closing rules and regeneration footer (shared by compact provider serializers and Providers::RulesOrchestrator).

Parameters:

  • context (Hash) —

    introspection context (+:conventions+ optional for architecture line)

  • rules_heading (String) (defaults to: '## Rules') —

    markdown ## ... line opening the rules section (default: ## Rules)

Returns:

  • (Array<String>) —

    markdown lines



179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
 
# File 'lib/rails_ai_bridge/serializers/shared_assistant_guidance.rb', line 179

def compact_engineering_rules_footer_lines(context, rules_heading: '## Rules')
  arch = context.dig(:conventions, :architecture)
  arch_summary = arch&.any? ? arch.join(', ') : nil

  lines = [
    rules_heading,
    '',
    '- **Adhere to Conventions:** Strictly follow the existing patterns and conventions outlined in this document.',
    '- **Schema as Source of Truth:** Always use the database schema as the definitive source for column names, types, and relationships.',
    '- **Respect Existing Logic:** Ensure all new code respects existing associations, validations, and service objects.',
    '- **Write Tests:** All new features and bug fixes must be accompanied by corresponding tests.'
  ]
  lines << "- **Match Architecture:** Align with the project's architectural style (#{arch_summary})." if arch_summary
  lines << "- **Verify Correctness:** Run `#{ContextSummary.test_command(context)}` and `bundle exec rubocop` after making changes to ensure correctness and style adherence."
  lines << ''
  lines << '---'
  lines << RegenerationFooter.message_line(command: 'rails ai:bridge', variant: :context_file)
  lines
end

.compact_engineering_rules_lines ⇒ Array<String>

Returns markdown lines including heading and trailing blank line.

Returns:

  • (Array<String>) —

    markdown lines including heading and trailing blank line



17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
 
# File 'lib/rails_ai_bridge/serializers/shared_assistant_guidance.rb', line 17

def compact_engineering_rules_lines
  [
    '## Engineering rules (read first)',
    '',
    'Defaults for this codebase unless existing files clearly show a different pattern.',
    '',
    '### Controllers & strong parameters',
    '- Permit attributes explicitly; never pass raw `params` into `Model.new`, `update`, or `assign_attributes`.',
    '- Extend `permit` lists deliberately when adding fields; mirror neighboring actions in the same controller.',
    '',
    '### Authentication & authorization',
    "- Guard mutating and sensitive reads with the app's existing auth (e.g. `before_action` filters, policies). A public route does not imply public data.",
    '- Use `rails_get_controllers` for filters and `rails_get_conventions` for architecture hints when unsure.',
    '',
    '### Data access & performance',
    '- Avoid N+1: use `includes` / `preload` / `eager_load` for associations used in views or serializers.',
    '- Do not load unbounded collections: paginate list endpoints, use `find_each` in jobs, stream large exports.',
    '- Large or hot tables: check indexes before new `WHERE`/`ORDER BY`; use `rails_get_schema` before heavy queries.',
    '',
    '### Security & inputs',
    '- Treat external input as untrusted; avoid `constantize` / `send` / `eval` on user-controlled strings and raw SQL string interpolation.',
    '- Allow-list host or path for any redirect built from user input (open-redirect risk).',
    '',
    '### Testing',
    '- Prefer request or system specs for HTTP flows and integration; keep model specs tight for business rules.',
    "- Run the project's test suite after substantive edits (often `bundle exec rspec` — confirm framework via `rails_get_test_info`).",
    '',
    '### Repo-specific constraints',
    '- Hot tables, tenant/auth scoping, mandatory spec types, and internal policies belong in `config/rails_ai_bridge/overrides.md`.',
    '- Remove the first-line `<!-- rails-ai-bridge:omit-merge -->` stub marker before that file is merged into Copilot/Codex; ' \
    'use `overrides.md.example` as a starting outline.',
    '',
    '_Regenerated files are snapshots. Re-merge team-specific performance, security, or compliance rules at the top after `rails ai:bridge`, ' \
    'or keep them in separate committed instruction files._',
    ''
  ]
end

.cursor_engineering_mdc_body_lines(show_overrides_pointer: false) ⇒ Array<String>

Condensed rules for always-on Cursor MDC (stay under ~35 lines of body).

Parameters:

  • show_overrides_pointer (Boolean) (defaults to: false) —

    append pointer to +config/rails_ai_bridge/overrides.md+

Returns:

  • (Array<String>) —

    markdown body lines (no YAML frontmatter)



75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
 
# File 'lib/rails_ai_bridge/serializers/shared_assistant_guidance.rb', line 75

def cursor_engineering_mdc_body_lines(show_overrides_pointer: false)
  lines = [
    '# Engineering essentials',
    '',
    '- **Strong params**: permit explicitly; never mass-assign raw `params`.',
    '- **Auth**: protect mutations and sensitive reads; public route ≠ public data.',
    '- **N+1**: `includes` / `preload` / `eager_load` for associations in views and serializers.',
    '- **Bounds**: paginate HTTP lists; `find_each` / `in_batches` in jobs; no `Model.all` in requests.',
    '- **Large tables**: narrow queries; check indexes before new filters/sorts; use `rails_get_schema`.',
    '- **Security**: no `constantize`/`send`/`eval` on user input; no SQL string interpolation; allow-list redirects.',
    '- **Tests**: request/system specs for HTTP; confirm runner with `rails_get_test_info`.',
    '',
    'Generated files are **snapshots** — prefer `rails_*` MCP tools for current structure.',
    'Full engineering rules: `.github/copilot-instructions.md` or `AGENTS.md`.',
    'MCP tool reference: `rails-mcp-tools.mdc`.'
  ]
  lines << 'Repo-specific performance/security: `config/rails_ai_bridge/overrides.md`.' if show_overrides_pointer
  lines << ''
  lines
end

.mergeable_override_content?(body) ⇒ Boolean

Returns +false+ when the install stub has not been activated yet.

Parameters:

  • body (String) —

    trimmed file contents

Returns:

  • (Boolean) —

    +false+ when the install stub has not been activated yet



116
117
118
119
120
121
122
 
# File 'lib/rails_ai_bridge/serializers/shared_assistant_guidance.rb', line 116

def mergeable_override_content?(body)
  first = body.each_line.map(&:strip).find { |line| !line.empty? }
  return false if first.nil?
  return false if OMIT_MERGE_FIRST_LINE.match?(first)

  true
end

.overrides_file_exists_and_nonempty? ⇒ Boolean

Returns whether overrides are active (merge + Cursor pointer), not placeholder-only.

Returns:

  • (Boolean) —

    whether overrides are active (merge + Cursor pointer), not placeholder-only



110
111
112
 
# File 'lib/rails_ai_bridge/serializers/shared_assistant_guidance.rb', line 110

def overrides_file_exists_and_nonempty?
  read_assistant_overrides != nil
end

.performance_security_and_rails_examples_lines ⇒ Array<String>

Baseline bullets plus concrete Rails patterns for large data.

Returns:

  • (Array<String>) 


202
203
204
 
# File 'lib/rails_ai_bridge/serializers/shared_assistant_guidance.rb', line 202

def performance_security_and_rails_examples_lines
  ContextSummary.compact_performance_security_section + rails_performance_examples_lines
end

.rails_performance_examples_lines ⇒ Array<String>

Concrete Rails patterns to complement generic performance bullets (gem cannot know your largest tables).

Returns:

  • (Array<String>) —

    markdown lines including heading; no trailing blank line required (caller adds spacing)



58
59
60
61
62
63
64
65
66
67
68
69
 
# File 'lib/rails_ai_bridge/serializers/shared_assistant_guidance.rb', line 58

def rails_performance_examples_lines
  [
    '### Rails patterns (large data & hot paths)',
    '- Never use `Model.all` (or unscoped relations) in request cycles — use `where`, `limit`, or pagination.',
    '- Background jobs: iterate with `find_each` or `in_batches` instead of `each` on large relations.',
    '- Prefer `exists?` / `count` with care on huge tables; narrow with `where` first; avoid `length` on loaded associations for big sets.',
    '- Wide rows: fetch only needed columns with `select` / `pluck` when you do not need full records.',
    '- Enable or use `strict_loading` in development/test to catch accidental N+1s early.',
    '- Before adding filters or `ORDER BY` on high-volume tables, confirm indexes via `rails_get_schema` and migrations.',
    ''
  ]
end

.read_assistant_overrides ⇒ String?

Returns raw markdown body from the host app overrides file, or +nil+ if missing, empty, or still in stub mode (first non-empty line is +<!-- rails-ai-bridge:omit-merge -->+).

Returns:

  • (String, nil) —

    raw markdown body from the host app overrides file, or +nil+ if missing, empty, or still in stub mode (first non-empty line is +<!-- rails-ai-bridge:omit-merge -->+).



98
99
100
101
102
103
104
105
106
107
 
# File 'lib/rails_ai_bridge/serializers/shared_assistant_guidance.rb', line 98

def read_assistant_overrides
  path = resolved_assistant_overrides_path
  return nil unless path && File.file?(path)

  body = File.read(path).strip
  return nil if body.empty?
  return nil unless mergeable_override_content?(body)

  body
end

.repo_specific_guidance_section_lines ⇒ Array<String>

Returns section to splice after stack; empty if no overrides.

Returns:

  • (Array<String>) —

    section to splice after stack; empty if no overrides



140
141
142
143
144
145
146
147
148
149
150
 
# File 'lib/rails_ai_bridge/serializers/shared_assistant_guidance.rb', line 140

def repo_specific_guidance_section_lines
  body = read_assistant_overrides
  return [] unless body

  [
    '## Repo-specific guidance',
    '',
    body,
    ''
  ]
end

.resolved_assistant_overrides_path ⇒ String?

Returns absolute path to overrides file if Rails app is available.

Returns:

  • (String, nil) —

    absolute path to overrides file if Rails app is available



125
126
127
128
129
130
131
132
133
134
135
136
137
 
# File 'lib/rails_ai_bridge/serializers/shared_assistant_guidance.rb', line 125

def resolved_assistant_overrides_path
  return nil unless defined?(Rails) && Rails.application

  base = Rails.application.root.to_s
  cfg = RailsAiBridge.configuration
  raw = cfg.assistant_overrides_path
  if raw.nil? || raw.to_s.empty?
    File.join(base, 'config/rails_ai_bridge/overrides.md')
  else
    p = raw.to_s
    Pathname.new(p).absolute? ? p : File.join(base, p)
  end
end