In short:
ak-brainstormturns a fuzzy idea into a clear decision: what to build, what not to build, when it is done, and how. It reads your real code, compares up to 3 approaches, recommends one, then hands off toak-planorak-fix. It does not write code.
Disclosure: I maintain AgentKit and have an affiliate relationship with it: the AgentKit link in this post is an affiliate link; buying through it gets you 30% off.
Summary
Use it when you know what you want but not how to get there, when you are torn between two directions, or when you hit a bug with no clear cause. You do not need it for a one-step question like "what does this function do?".
flowchart LR
A["Fuzzy idea"] --> B["ak-brainstorm"]
B --> C["4-point contract + chosen approach"]
C --> D["ak-plan then ak-cook"]
C --> E["ak-fix"]
C --> F["Stop, exploration only"]It always settles 4 points:
| Point | Question | Example |
|---|---|---|
| Outcome | What does the user see when it is done? | Click "Sign in with Google" and land on the dashboard |
| Constraints | What must not break? | Keep email sign-in, do not change the users table |
| Non-goals | What is nearby but not in scope this time? | No GitHub or Apple sign-in |
| Acceptance | What evidence shows it is done? | Google e2e test passes, existing users still sign in |
With 2 or more approaches, it also records the trade-offs: which assumption each approach rests on and where it breaks first. When the choice shapes a boundary that several variants share, it tests a real second case before recommending a seam. For a bug, it proves the cause before discussing a fix.
Sample prompt for a new feature:
/ak-brainstorm Add Google sign-in to the <app name> app.
Outcome: users click "Sign in with Google" and land on the dashboard.
Constraints: keep the existing email/password sign-in, do not change the users table schema.
Not doing: GitHub/Apple sign-in, merging accounts with the same email.
Done when: there is an e2e test for the Google flow and existing users can still sign in.The prompts in this guide use the Claude Code and Cursor form /ak-brainstorm. On Codex, type $ak-brainstorm instead.
| Flag | What it is for | Since ak |
|---|---|---|
--ask | Asks you one round, up to 4 questions, when the code cannot answer | 2.16.0 |
--report | Saves the decision as a Markdown file | 2.13.0 |
--html | Also writes an HTML file with diagrams to view or share | 2.5.0 |
--ak-render | Builds the HTML file with AK Render, implies --html | 3.0.0-beta.5 |
--advice | A stronger model reviews at key checkpoints | 2.5.0 |
--ultra | Runs 5 independent passes and keeps one winner whole | 2.13.0 |
--yagni | Cuts down to the smallest version that does the job | 2.8.0 |
--no-antv, --no-diagram-design, --no-editorial-visuals | Turns off illustrations in the HTML file | 2.13.0 |
Below is the detailed version: the run flow, 6 situations with prompts, each flag explained (when to use it, when you do not need it, what you get, which flags it combines with), the change history by ak release, and common pitfalls. The detailed version and the interactive page are for subscribers. Your agent can also search them through the portal's MCP.
Opens when your account has subscriber access
This guide is for subscribers
Once your account has access, the full piece, the interactive visual and the agent call all open.
- Sign in or create a modernEngineer accountReading access belongs to your account email.
- Choose a plan on the pricing page1, 3 or 12 months, paid by VietQR bank transfer. Access opens about a minute after the money arrives.
- Or redeem a Facebook subscriber codePeople supporting the page on Facebook get an activation code by message each month.
Already a subscriber? Sign in to read.
Use this piece in your agent
Get an API keyCopy the text below and paste it into Claude Code, Codex or whichever agent you use. The agent reads the piece and checks it against the repo you have open.
Read "ak-brainstorm: settle what to build and how before you code" on modernEngineer and apply it to this repo.
1. Call the content_get tool of the modernengineer MCP server with locale "en", slug "ak-brainstorm". If the modernengineer MCP server is not connected, stop and walk me through connecting it from https://modernengineer.dev/en/mcp.
2. Summarize the main steps of the piece and point out which apply to this repo.
3. Propose concrete changes and ask me before editing any file.Connect MCP in Claude Code (once)
claude mcp add --transport http modernengineer \
https://api.modernengineer.dev/mcp \
--header "Authorization: Bearer <API key>"Reading the full piece over MCP needs an API key from a subscriber account or one that bought this guide. Without access, the agent only gets the opening.
- Version
- v1.0.0
- Updated
- 21/10/2026
- Licence
- All rights reserved
- Slug
- ak-brainstorm
