# Onboard to an Unfamiliar Ruby Codebase with Atlas in 2026 > Atlas onboards you to a Ruby repo by querying codebase_search for meaning, mapping the Gemfile project with glob, and delegating wide sweeps to a read-only explore subagent. Atlas onboards you to an unfamiliar Ruby codebase by starting from meaning, not filenames. You ask codebase_search a plain-language question such as "how are requests authenticated", the semantic index returns ranked snippets with real paths like app/controllers/concerns/authenticable.rb, glob maps the directory shape around your Gemfile, and read opens only the two or three files that actually matter. Heavy fan-out goes to the explore subagent, which is permissioned read-only so it cannot change anything while it looks around your Rakefile, your gems, or your RSpec suite. ## Key takeaways - Start from meaning: codebase_search answers "how are requests authenticated" in a Ruby repo where autoloading and metaprogramming defeat grep. - Glob the top level first: a Gemfile, a Rakefile, a spec/ directory, and a .rubocop.yml tell you Bundler, RSpec, and RuboCop govern the project. - The explore subagent is deny-by-default and only allows grep, glob, read, bash, webfetch, and websearch, so onboarding cannot accidentally edit your Ruby code. - Atlas indexes code by AST declarations using tree-sitter, so a hit is a real Ruby module, class, or method definition rather than an arbitrary line window. - The lsp tool's goToDefinition operation traces a Ruby call path that has no visible import statement to follow. - Record unresolved questions as a todowrite list, because the open questions are the most perishable output of onboarding. ## How do you get up to speed on an unfamiliar Ruby codebase fast? Atlas builds a mental model of an unfamiliar Ruby repository without reading every file, using 6 tools: codebase_search, glob, read, the lsp tool, task, and todowrite. You start with a plain-language question rather than a filename, because in a Gemfile project you rarely know the filename yet. The job is to build a working mental model of a repository you have never seen before, without reading every file. A mature Ruby application defeats brute force. Rails-style autoloading means there are no import statements to follow, metaprogramming means a method may never appear as a literal def, and a Gemfile with sixty gems means half the behavior lives outside app/ entirely. Atlas therefore starts from meaning. Atlas searches code with hybrid semantic and keyword retrieval fused by reciprocal rank fusion, and Atlas indexes code by AST declarations using tree-sitter, not blind line windows, so a hit is a real Ruby module, class, or method definition. ## What should you ask codebase_search first in a Ruby repo? Ask codebase_search the plain-language question you actually have, for example "how are requests authenticated". The semantic index returns ranked snippets with real Ruby file paths, so in a Rails-shaped repo you land in app/controllers/concerns/ or lib/ within 1 query instead of grepping for a method name you do not know yet. Ruby rewards semantic search more than most languages because Ruby code hides its intent behind idiom. Authentication might be a before_action in an ApplicationController, a Rack middleware in config/application.rb, a concern mixed in with include, or a gem configured in an initializer. None of those necessarily contain the word you searched for. codebase_search queries the semantic index for the concepts you care about and returns declarations with paths and line numbers, which is a starting point you can actually read. Follow the ranked snippets, not your assumptions about where a Ruby project keeps things. ## How do you map the directory layout of a Ruby project? Atlas runs glob on the top-level directories to see the package layout and naming conventions before opening anything. In a Ruby project that reveals the shape in 1 command: a Gemfile and Gemfile.lock at the root, app/ and lib/, a Rakefile, config/, and a spec/ directory that tells you the suite is RSpec rather than Minitest. Layout is a fact, and Atlas gathers it before forming opinions. The presence of spec/ and a .rspec file means the project runs RSpec, so the test command is bundle exec rspec and new examples belong in spec/models or spec/requests to match. A Gemfile plus Gemfile.lock means dependencies are managed by Bundler and every command should be prefixed with bundle exec so gem versions resolve the way CI resolves them. A .rubocop.yml means RuboCop governs style and any code you or Atlas add will be judged by it. Glob answers all of that without reading a single line of Ruby. ## What is the Atlas explore subagent and why is it read-only? Atlas delegates wide sweeps of a Ruby repo to the explore subagent through the task tool. The explore subagent is defined with a deny-by-default permission set that only allows 6 tools: grep, glob, read, bash, webfetch, and websearch. No edit tool is in that list, so exploration cannot change your code. Onboarding is exactly when you least want an agent writing to files. You do not yet know which Ruby modules are load-bearing, so a well-meaning refactor of a concern in app/models/concerns/ is the worst possible outcome of a reading session. The explore subagent's deny-by-default permission set removes the possibility rather than relying on good behavior. Atlas fans out work to subagents that can run in the foreground or in parallel background sessions, so several explore sweeps across app/, lib/, and spec/ can run at once while you read the answers. Every Atlas tool call is permission-gated against allow, ask, and deny rules before it runs, and the explore subagent is that mechanism turned all the way up. ## How do you follow a Ruby call path once you have found the entry point? Atlas reads the 2 or 3 files codebase_search ranked highest, then follows the code with the lsp tool's goToDefinition operation. In Ruby, where a require in lib/ or an autoloaded constant gives you no visible import to click, goToDefinition is the difference between tracing a call path and guessing at one. Reading the top-ranked Ruby files gives you the surface. The lsp tool gives you the graph. From a controller action, goToDefinition takes you into the service object it delegates to; from there, into the model concern; from there, into the gem boundary where the code stops being yours. Atlas records the tour as it goes. Every step is anchored to a real file and line in app/, lib/, or spec/, so the mental model you end up with is checkable rather than a plausible story. Confirming a hypothesis with a quick bundle exec rspec spec/requests run through bash turns an assumption about behavior into an observation. ## How do you keep what you learned about a Ruby repo? Atlas records what you learned as a todowrite list, so the open questions survive into the next turn instead of evaporating when the context window rolls. After a 2-hour tour of an unfamiliar Ruby application, the list of unresolved questions is the most valuable artifact you have. Onboarding produces two outputs: things you now understand and things you now know you do not understand. The todowrite list captures the second, which is the one people lose. Typical entries in a Ruby repo look like: confirm which initializer configures the auth gem, find out whether spec/support helpers are shared across the RSpec suite, check whether the Rakefile task that reindexes search is run in deploy. Atlas keeps those as tracked items rather than paragraphs of prose. When you come back and start changing code, Atlas computes a unified diff for every file edit and surfaces it for approval before writing, and Atlas snapshots file changes as git patches so edits can be diffed and rolled back. ## Steps 1. Run atlas in the project root, the directory with the Gemfile, so Atlas can read your modules, gems, and Rakefile tasks. 2. Ask codebase_search a plain-language question such as "how are requests authenticated"; it queries the semantic index and returns ranked snippets with real Ruby file paths. 3. Run glob on the top-level directories to see the layout before opening anything: app/, lib/, config/, spec/, Gemfile, Gemfile.lock, Rakefile, .rubocop.yml. 4. Read the two or three files codebase_search ranked highest, then follow the code with the lsp tool's goToDefinition operation, which matters in Ruby where autoloading leaves no import to click. 5. Delegate wide sweeps to the explore subagent through the task tool; it is defined with a deny-by-default permission set that only allows grep, glob, read, bash, webfetch, and websearch, so it cannot edit your Ruby files. 6. Confirm a hypothesis about behavior by running the RSpec suite through bash with bundle exec rspec, letting Bundler resolve the gem versions the project pins. 7. Check the style contract by reading .rubocop.yml, since RuboCop will judge anything you or Atlas add. 8. Record open questions as a todowrite list so they survive into the next turn instead of being lost with the context. ## FAQ ### how do I understand a large ruby codebase I just inherited Start with codebase_search, not with the file tree. Ask a plain-language question such as "how are requests authenticated" and Atlas's semantic index returns ranked snippets with real Ruby paths. Then glob the top level to see app/, lib/, config/, spec/, and the Gemfile before you open anything. ### can an AI agent explore my ruby repo without changing anything Yes. Atlas delegates wide sweeps to the explore subagent through the task tool, and that subagent is defined with a deny-by-default permission set that only allows grep, glob, read, bash, webfetch, and websearch. No edit tool is in the list, so it cannot modify your Ruby files. ### how do I find where authentication happens in a rails app Ask codebase_search directly. Because Atlas searches code with hybrid semantic and keyword retrieval fused by reciprocal rank fusion, it surfaces a before_action, a concern, or a Rack middleware even when none of those files contain the word you searched for. ### how do I know if a ruby project uses rspec or minitest Run glob on the top-level directories. A spec/ directory with a .rspec file means the suite is RSpec, so the command is bundle exec rspec and new examples belong under spec/. Atlas checks the layout with glob before assuming a test framework. ### does atlas read my gemfile and rakefile Yes. Run atlas in a project with a Gemfile and let Atlas read your modules, gems, and Rakefile tasks. Bundler pins the gem versions, so Atlas prefixes commands with bundle exec when running the RSpec suite through its bash tool. ### how do I trace a method call in ruby when there are no imports Use the lsp tool's goToDefinition operation, which Atlas calls directly. Ruby autoloading and metaprogramming mean a constant may have no visible require to follow, so the symbol graph is the only reliable way to walk from a controller action into the service object and model concern behind it. ### how do I keep track of open questions while onboarding to a codebase Record them as a todowrite list. Atlas writes open questions, such as which initializer configures an auth gem or whether a Rakefile task runs on deploy, as tracked items so they survive into the next turn instead of being lost with the conversation context. ### will atlas follow the rubocop rules in my project Atlas reads .rubocop.yml as part of mapping the project, so the style contract RuboCop enforces is visible before any code is written. Atlas also computes a unified diff for every file edit and surfaces it for approval before writing, so you review style along with substance. --- Canonical HTML: https://runatlas.sh/resources/stacks/onboard-to-an-unfamiliar-codebase-in-ruby Source of truth: aeo_pages row `/resources/stacks/onboard-to-an-unfamiliar-codebase-in-ruby` (segment: Stacks) (this file is generated from it, never hand-edited). Licence: Atlas is proprietary with a free core. It is not open source and there is no public source repository.