110 Asking your agent about APIs and libraries [0.5d]

Your agent is the fastest way to learn how a method, gem or library works — if you ask well, and if you know how to make it prove its answers. This lesson teaches both, and shows where the canonical documentation lives when you want to learn instead of look up.

Important

Work on this lesson in teacher mode.

Learning goals

• You can get an answer about a method, gem or library from your agent that applies to the exact versions installed in your project.
• You can make the agent back up an uncertain answer, e.g. by citing sources, searching the web or running an experiment in the app — and you prefer the experiment.
• You can find out where a method is defined and whether it comes from Ruby, ActiveSupport or a gem.
• You know the canonical documentation for each part of our stack, and you read it to get an overview of a tool rather than to look up a single method.

Asking your agent

Your agent is the first place to ask "how does this method work?" or "how do I do X with library Y?". It has your whole repository, so it knows the exact versions of every gem and package you use (Gemfile.lock, yarn.lock), it can read the installed source of any library, and it can search the web or fetch a documentation page you point it at. Give it that context: name the library, paste the snippet or error, say what you're trying to do. "What options does validates take in our Rails version?" gets a better answer than "how do validations work?".

Most answers are right. When one feels off — an option you've never seen, an API that seems too convenient, an answer that changes when you ask twice — don't go and check by hand. Push the agent:

• Double-check. "Are you sure? Check again." Often enough on its own.
• Search the web. "Look this up in the current documentation."
• Cite sources. "Show me where that's defined and link the docs." A good answer points at a file and line in the installed gem, or a page in the official docs.
• Run an experiment. "Try it in the app and show me the result." A rails runner one-liner, a console session or a throwaway spec settles most questions in seconds — and the result is proof, not opinion.

The experiment is the strongest of the four. Prefer it whenever the question is "does this actually work?".

Using documentation to learn

Reference documentation is still the best way to get an overview of a tool and to learn how its authors think it should be used. When you're about to work with a library for the first time, or you keep asking the agent about the same one, read its guide: the Rails Guides, MDN, a gem's README. You'll ask better questions afterwards.

Resources

Read what's new to you, skim what's familiar, skip what you already master. Stop when you can meet the learning goals.

Your agent can also generate an overview, a tutorial or an explanation for anything here, tailored to what you already know. Just ask.

This is the map of canonical documentation for our stack. You don't need to memorize it; your agent will point you to the right place when you ask.

Ruby

• 📄 Ruby 4.0 documentation Show archive.org snapshot — official docs for core classes, the standard library and syntax ( all versions Show archive.org snapshot )
• 📄 RubyAPI Show archive.org snapshot or DevDocs: Ruby Show archive.org snapshot — the same docs with a better search box

Ruby on Rails

• 📄 Rails Guides Show archive.org snapshot — read a guide when you start using a part of Rails
• 📄 Rails API Show archive.org snapshot — method-level reference
• 📄 Active Support Core Extensions Show archive.org snapshot — Rails adds methods to Ruby's core classes, e.g. Array#to_sentence Show archive.org snapshot , String#dasherize Show archive.org snapshot or Object#presence Show archive.org snapshot . We are so used to Active Support that we don't think of it as separate from Ruby, so some methods you'd expect in the Ruby docs are in the Rails docs. It also works the other way: Hash#slice started in Active Support and has been part of Ruby since 2.5.
• 📄 Method#source_location Show archive.org snapshot and Method#owner — find out where a method is defined and which class or module it belongs to; bundle open GEM opens the installed source of a gem

Gems and JavaScript libraries

• 📄 The README in a library's GitHub repository is its manual, e.g. active_type Show archive.org snapshot or timecop Show archive.org snapshot .
• 📄 Some libraries have a dedicated documentation site, e.g. Unpoly Show archive.org snapshot .

Web platform (HTML, CSS, JavaScript)

• 📄 MDN Web Docs Show archive.org snapshot — the reference for HTML elements, CSS properties and JavaScript features; use the English version

External services

• 📄 Vendors publish language-independent API docs, e.g. Stripe Show archive.org snapshot or Twilio Show archive.org snapshot

Everything else

• 🎮 DevDocs Show archive.org snapshot — one search box over most of the above; you can add the languages and libraries you use as a default profile

Exercises

Look things up

For each of these, ask your agent what it does, where it's defined or documented (make it link the docs), and have it prove one of its claims with a small experiment — an irb session or a throwaway script; for the HTML one, a throwaway .html file in your browser:

• Ruby: Array#tally
• HTML: the <details> and <summary> elements
• JavaScript: structuredClone

You met none of these in the lessons so far — that's the point: this is what looking up an unknown feature will feel like for the next months.

Two search missions

Push the agent while you research: make it cite sources, and have it demonstrate options with small experiments. Afterwards you should be able to explain your favorite — and why you rejected the others — to your mentor without notes.

1. Research ways to count the lines of a resource behind an HTTPS URL in Ruby. Compare at least three options (e.g. standard library vs. a gem vs. shelling out), understand their pros and cons, pick a favorite — and type and run that favorite yourself once.
2. Research ways to let users pick a date in an HTML form, with and without JavaScript. Understand the trade-offs (browser support, consistency, dependency cost), and pick a favorite for a typical form.