Do Agents need Quickstart Guides?

Companies are laying off their entire documentation teams. Who needs them, when agents can figure stuff out without documentation, or write documentation themselves?

But I've been noticing that even when building with agents, quickstart guides seem to help. We first saw this while working on documentation for a client: before the quickstart existed, agents struggled to produce anything that was a good representation of the product's features. After it was published, agents found it, followed it, and the results were noticeably better.

To test if the benefit of quickstart guides was repeatable, I picked Infisical, a widely-used secrets manager with solid documentation, but with short and incomplete getting started guides. I gave Claude the same integration task twice, first with only the existing documentation and then again after adding a new and detailed quickstart.

With the new guide, Claude reached a goal faster and without any additional help from me. It used half the number of tokens, and it chose to use the CLI instead of the SDK which was more appropriate for the task. Here's a summary of the most interesting results.

Figuring out the 'hello world' of Infisical​

To figure out what a new platform is and how it works, it's useful to build whatever the 'hello world' equivalent is. For Infisical this is using the CLI to

• create a project
• add a secret
• retrieve the secret

I found some friction caused by figuring out which of several plausible-looking paths was the right one. Infisical has Machine Identities, Universal Auth, project-level and org-level access controls, a CLI, SDKs in a dozen languages, and a broad documentation site. None of that is bad, but for someone new there's no obvious "start here" path.

The agent and I hit the same walls. Creating a Machine Identity at the wrong level was the first. The agent directed me to Organisation Access Control → Identities, but the correct path is under Project Access Control → Machine Identities, a different section with a different flow. Without knowing the distinction between org-level and project-level identities, I spent time clicking through the wrong menus.

Then there was infisical bootstrap, which sounds like the entry point for first-time setup. However, it only works for self-hosted instances. On Infisical Cloud, it doesn't exist. The agent tried it, got an error, and had to reroute.

After a few sessions of trial and error, I had a working mental model with a basic understanding of the key concepts, which CLI commands actually matter, and what the right integration pattern looks like for a typical app. I had a toy project that could do the basic operations of adding and retrieving secrets from the platform.

Then I wrote a quickstart guide to capture what I'd learned, trying to make something that could be useful for the next person (or agent) going through the same process.

Beyond hello world: A URL Shortener That Needs a Database Secret​

With the quickstart written, I needed a test that resembles something real, even if still basic.

I set up a URL shortener (without Infisical) to use as an example: an Express app backed by Postgres, storing slugs and redirect URLs in a database. The app reads DATABASE_URL from environment variables.

My goal was to move that credential into Infisical so the app works without a .env file, and a teammate could hypothetically clone the repo and run it without any shared secrets.

I copied the app into two directories and ran a Claude Code session in each. Both got the same prompt:

You have two goals. Integrate this project with infisical appropriately:
1. Remove the .env file — the app fetches its credentials from Infisical
   at startup and connects to the database without a .env present
2. A teammate can clone the repo and run the app by pointing it at the
   same Infisical project — no credentials handed to them out of band

But for the second session, I added one sentence:

Before you start read: /docs/documentation/getting-started/quickstart.mdx

The quickstart.mdx file was the guide I'd written as part of building the hello world example.

Run 1: Without the quickstart guide, the agent struggled​

The Claude session with no extra help started by reading the project files and finding the .env with DATABASE_URL. Interestingly, its first instinct was to reach for the SDK rather than the CLI:

npm install @infisical/sdk

It then spent a dozen tool calls reading through the SDK's TypeScript definition files to work out the API:

cat node_modules/@infisical/sdk/dist/index.d.ts | head -80
grep -A 30 "class InfisicalClient" node_modules/@infisical/sdk/lib/index.d.ts
grep -n "GetSecretOptions\|workspaceId\|projectId" node_modules/@infisical/sdk/lib/index.d.ts

Then it rewrote server.js to authenticate with Infisical and fetch each secret at startup, before any application code ran:

const { InfisicalSDK } = require("@infisical/sdk");

async function main() {
  const client = new InfisicalSDK();
  await client.auth().universalAuth.login({
    clientId: process.env.INFISICAL_CLIENT_ID,
    clientSecret: process.env.INFISICAL_CLIENT_SECRET,
  });
  const dbUrlSecret = await client.secrets().getSecret({
    environment: "dev",
    projectId: process.env.INFISICAL_PROJECT_ID,
    secretName: "DATABASE_URL",
  });
  const pool = new Pool({ connectionString: dbUrlSecret.secretValue });
  // ...
}

It works, but it's a more involved approach than necessary. The SDK credentials (INFISICAL_CLIENT_ID, INFISICAL_CLIENT_SECRET, INFISICAL_PROJECT_ID) still need to come from somewhere, typically a new .env file, which partially defeats the point. It also adds a dependency and rewrites application logic that didn't need to change. Infisical's own recommended path for most apps is infisical run, which injects secrets as environment variables before your process starts with no code changes required. The SDK is there for cases where you need more control at runtime, but for an app that just reads env vars, the CLI wrapper is the right starting point.

After implementing the SDK, the agent needed to create an Infisical project via the API and add a Machine Identity to it. It couldn't find API documentation for these endpoints, so it ended up probing the API by guessing endpoint paths.

It took two wrong guesses to find the project creation endpoint:

# Not found
POST /api/v1/workspace

# Wrong, different body schema
POST /api/v2/workspace

Claude also struggled to add a Machine Identity to the project. It took five attempts, trying both v1 and v2 endpoints before finding a working endpoint:

POST /api/v2/workspace/{projectId}/identity-memberships        # wrong
GET  /api/v1/identities/{identityId}/identity-memberships      # probing, read-only
POST /api/v1/projects/{projectId}/memberships/identities       # 404
POST /api/v1/projects/{projectSlug}/memberships/identities     # 404
POST /api/v2/workspace/{projectId}/identity-memberships/{identityId}  # worked

The session ran to 263 lines of context. Full transcript.

Claude had managed to complete both goals I had set. The app uses the Infisical SDK to fetch the credentials at run-time and a teammate could use their Infisical account to get the same result. However, this requires the INFISICAL_CLIENT_SECRET environment variable in order to interact with Infisical.

Claude walked me through setting it up and it was fairly easy to do, but still more manual work that needed a human to carry out.

Not only did it require manual steps, it also mostly invalidates the purpose of the integration. We're just storing our credentials on a cloud server and then pointing to them with a different set of credentials. If your .env file leaked, someone could still access your accounts.

Run 2: With the quickstart guide, everything was much smoother​

The second session had the same prompt with the extra line:

Before you start read: /docs/documentation/getting-started/quickstart.mdx

It read the quickstart before doing anything else, then installed the CLI and authenticated it:

infisical --version && infisical whoami

This was a single-click login flow through the browser. From there, the agent created the project and pushed the correct secret values.

This flow stores a JWT that is used for Infisical authentication when running the actual app through infisical run.

The only change to server.js was removing one line:

- require("dotenv").config();

Everything else was wiring. It updated package.json to prefix each start script with infisical run:

"scripts": {
  "dev": "infisical run --env=dev -- node server.js",
  "start": "infisical run --env=dev -- node server.js",
  "db:start": "infisical run --env=dev -- docker-compose up -d"
}

It wrote .infisical.json to link the repo to the Infisical project: just a project ID and branch-to-environment mapping. Then it deleted the .env and added an .env.example explaining to a future teammate where credentials come from and what commands to run.

The session completed with no user input in 132 lines. Below is the output of the URL shortener running through infisical run:

> infisical run --env=dev -- node server.js

INF Injecting 5 Infisical secrets into your application process
Listening on http://localhost:3002

$ curl localhost:3002/shorten -H "Content-Type: application/json" \
    -d '{"url":"https://example.com"}'

{"short_url":"http://localhost:3002/5cb3ac40","code":"5cb3ac40"}

This session was a far better "first impression" for Infisical. With the SDK approach, every developer joining the project needs to understand how the Infisical client is initialized and where the three SDK credentials come from. With infisical run, they just need the CLI and a set of credentials, and the app itself doesn't know Infisical exists. For a new teammate, the second is a much simpler setup. Full transcript

It also 'just worked' and didn't require the manual configuration that I needed to do for the first run.

The guided run was faster, cheaper, and more correct​

The guided run cost less than half as much, got to a fully working solution autonomously, and the solution was better.

Agents still need direction​

I think the assumption behind "agents don't need docs" is that trial and error is essentially free: a bit slower, maybe a few extra API calls, but the agent gets there eventually.

But what I saw in practice is that the agent without the guide made a different technical choice entirely. It reached for the SDK over the CLI because the SDK was more discoverable. The CLI approach required knowing that infisical run exists and is the recommended starting point. Without that context, the agent optimized for what it could find first rather than what was most appropriate.

I think this is the interesting part. Documentation tells the agent which path to take when several paths all look plausible from the outside.

The quickstart I wrote came from actual experience, and I think that's what made the difference. The parts that helped were things I'd had to figure out through my own trial and error: use infisical run over the SDK, which API endpoint creates a project, why infisical bootstrap is only relevant for a self-hosted setup.

A guide written purely from the outside wouldn't have known which bits to emphasize. The most useful documentation is written by someone who has done the thing and remembers where it was confusing.

This is only two runs of one product, and I wrote the guide specifically because I'd watched agents struggle without it. But the difference in both the approach chosen and the cost was clear enough that I'm confident in the takeaway: write the quickstart. Make it terminal-first. Show the right path, not all the paths. Agents are reading your docs now too, and they benefit from the same quality of writing that humans do.