plan-first

ASD-STE100 for coding: plan-first

English · 简体中文

plan-first makes your AI coding agent (Claude Code, Codex, Cursor and others) hand you a plan you can actually read before it touches your code. The plan follows the sentence rules of ASD-STE100 Simplified Technical English, the standard Karpathy suggested models write toward: short sentences, active voice, one name for each thing. You read it, answer the few questions it asks, and approve it before the agent writes any code. Add it to CLAUDE.md or AGENTS.md, or install it as a Claude Code plugin. It works with Claude Code's plan mode too.

Works with: Claude Code (tested), plus Codex, Cursor, Gemini CLI and other tools that read AGENTS.md or CLAUDE.md (untested). If you've been looking for CLAUDE.md rules or an AGENTS.md template that makes your agent plan before it codes, this is one.

Why

After coding with AI agents for a while, I realized reading had become my bottleneck. An agent can produce a plan of several thousand words, and usually only two or three things in it need my decision. The rest are details it could settle on its own. When a plan is that long, I end up approving it without really reading it.

In October 2026, Karpathy suggested asking models to write "80% of the way to ASD-STE100" to make their output easier to read. I'd already been doing something similar, so I packaged it as plan-first and applied it to the plans I approve, which is where readability matters most when you code with an agent. To be clear, plan-first isn't affiliated with Karpathy or with ASD, and it doesn't claim ASD-STE100 compliance.

Install

Pick one way. Installing both loads the rules twice.

Always on (recommended). Copy the rule files into your project and import them from CLAUDE.md:

mkdir -p docs/rules
curl -fsSLo docs/rules/plan-first.md https://raw.githubusercontent.com/AsherHou/asd-ste100-for-coding/main/plan-first/rules/en/plan-first.md
curl -fsSLo docs/rules/human-template.md https://raw.githubusercontent.com/AsherHou/asd-ste100-for-coding/main/plan-first/rules/en/human-template.md
echo "@docs/rules/plan-first.md" >> CLAUDE.md

For Chinese, replace en with zh-CN in the paths.

Claude Code plugin:

/plugin marketplace add AsherHou/asd-ste100-for-coding
/plugin install plan-first@asd-ste100-for-coding

The plugin kicks in automatically on development requests, and it uses the Chinese rules when you write in Chinese. You can also call it directly with /plan-first:plan-first <task>, or /plan-first:plan-first-zh for Chinese. It adds about 240 tokens to every session and about 6,000 each time it runs.

I haven't tested Codex, Cursor or Gemini CLI yet. Codex doesn't expand @ imports, so paste the full text of plan-first.md into AGENTS.md. For Cursor, put it in .cursor/rules/plan-first.mdc with alwaysApply: true. Gemini CLI can import it from GEMINI.md with @.

What it does

flowchart LR
    A[You ask for a change] --> B{Small fix?}
    B -- yes --> C[Agent does it and tells you what changed]
    B -- no --> D[Agent writes the detailed plan and the short plan]
    D --> E[You read the short plan and answer its questions]
    E -- approve --> F[Agent codes and commits]
    E -- change something --> D

For a feature, refactor, dependency change or API change, the agent writes two files with the same name:

• docs/plan/... is the detailed plan, for the agent. Another agent could carry out the task from this file alone.
• docs/human/... is the short plan, for you. It covers what this does, what you need to decide, what you need to do yourself, and what it will affect.

The short plan only asks you about product trade-offs, anything that's hard to undo, and anything that costs money or touches your accounts. Naming, file layout and similar details are the agent's call, and it records them in its own plan. Each question says whether the choice can be undone and comes with a recommendation.

There's no "Risks" section. Instead, each risk is designed away, turned into a decision for you, or added to the agent's plan as a checkpoint where it stops and asks.

Here is part of a short plan an agent wrote in one of my tests. The task was adding Google sign-in to an app that already had email and password login:

# Let people sign in to Tallybook with their Google account

> Status: Awaiting approval · v1 · 2026-10-07

## Decisions for you

1. **When should Tallybook connect Google to an existing account automatically?** (feature 2, can undo)
   - Recommended: Connect only when Tallybook has verified the address and Google controls it,
     as with Gmail or Google Workspace. About 9,000 accounts never verified their address,
     so a stranger could have created some of them.
   - Alternative: Connect every matching account automatically.

Before and after

Same task: adding Google sign-in, which I chose as the example before running the test. The plain agent's plan is about 1,100 words and plan-first's short plan about 1,000, so the real difference isn't length. It's what fills them.

A plain agent's plan opens like this:

# Plan: Sign in with Google

I haven't changed anything yet. Below is the plan, the decisions I need from you, and the setup work only you can do.

## Decisions I need from you

1. **How to handle existing accounts whose email was never verified (about 9,000).** This is the main security risk. Someone could sign up with a victim's address and a password they choose, without verifying it. If we then merge the victim's Google login into that account automatically, the attacker's password keeps working and they can read the victim's invoices.
   **My recommendation:** link automatically only when Google reports `email_verified: true`. If the Tallybook account was never verified, still link it, but in the same transaction:
   - mark the account verified,
   - remove the existing password,
   - end all of that user's existing sessions,
   - email them a notice.

   That is equivalent to a password reset, which Google's verified email justifies. The cost is that a legitimate user who never clicked the verification link loses their password and must use Google or "forgot password". The alternative is to refuse to link and send these users through password reset first. That is safer but adds friction.
2. **Preview deploys.** Google doesn't allow wildcard redirect URIs, so `pr-<n>.preview…` can't use Google sign-in. I'd keep the feature flag off on previews and test on local and staging. Is that acceptable?
3. **Which Google Cloud project to use.** I'd reuse `tallybook-prod` for the production client and create separate OAuth clients for staging and local, ideally in a separate non-prod project. While you're in that project, it's worth checking for API keys left over from the autocomplete experiment.

## Work only you (or counsel) can do

These block a production launch, not development:
- **Google Cloud console** (you're the only Owner). Set up:
  - an "External" OAuth consent screen with app name, logo, support email, the authorized domain `tallybook.example.com`, and links to the homepage and privacy policy;
  - scopes `openid email profile` only, which are non-sensitive, so no security review is needed;
  - publishing status "In production". In testing mode, only listed test users can sign in;
  - one Web OAuth client per environment, with these redirect URIs:
    - `http://localhost:3000/auth/google/callback`
    - `https://staging.tallybook.example.com/auth/google/callback`
    - `https://app.tallybook.examp