In short:
ak-fixtakes a concrete error such as a bug, a red test, a type or lint error, or a red CI run, proves the root cause first, fixes the right spot, then reruns the exact command that failed to prove it is gone. When it is done, it hands off toak-test. It does not fix from the symptom, does not keep guessing after 3 failures, and does not commit or push until you allow it.
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 have a real error: a bug with a symptom, a red test, a type or lint error, an error in the logs, a red CI run. You do not need it when you only have an idea or a new feature: start with ak-brainstorm instead.
flowchart LR
A["Concrete error: bug, red test, red CI"] --> B["ak-fix"]
B --> C["Cause + fix + before/after evidence"]
C --> D["ak-test"]
B --> E["3 failures: stop, discuss architecture with you"]
B --> F["All 5 rejected with --ultra: stop, say why"]It always keeps 4 principles:
| Principle | Question | Example |
|---|---|---|
| Cause first, fix second | Are all 6 points answered: the exact symptom, how to reproduce it, expected versus actual, the root cause down to file and line, why it shows up only now, and what else is affected? | "Users get signed out" is the symptom. "The session refresh function compares times in the server time zone at src/auth/session.ts:42, exposed by last week's server change" is the cause. |
| Pick the path by difficulty | After diagnosis, is the error clear and in one spot, spread across files, or does it touch the architecture? | A type error in one file takes the quick path. An error spread across 2 to 5 files takes the standard path. Memory leaks, deadlocks and security holes take the deep path: research more, call ak-brainstorm to compare fixes, write a plan, then fix. |
| Prove there are no side effects | Besides the spot just fixed, did anything else break? | Rerun the exact command that was red, add a regression test that goes red without the fix, run the tests of the callers of the changed function, check that function signatures, schemas, APIs and environment variables did not change. For type and lint errors, the checker itself is the evidence. |
| 3-attempt limit | What if the fix keeps failing? | A failed verification goes back to diagnosis. On the third failure it stops, lays out the evidence and reviews the architecture with you, instead of more guesswork. |
If the fix breaks something else within the assigned scope, it keeps fixing on its own. It only asks you when an important decision is missing, when an agreed contract has to change, or when it needs a destructive action you have not allowed.
Sample prompt for a bug with no clear location:
/ak-fix The <page name> page sometimes returns another account's data.
Repro: sign in to 2 accounts in 2 tabs, keep reloading the second tab.
Constraints: do not change the response format of the <API name> API.
Done when: a test reproduces it, the test passes after the fix, old tests stay green.| Flag | What it is for | Since ak |
|---|---|---|
--auto | Runs on its own from diagnosis and fix to verification, asks only when needed | 1.0.0 |
--review | Waits for your approval at each major step, including review | 1.0.0 |
--quick | A short path for clear errors in one spot | 1.0.0 |
--parallel | Fixes several independent errors in parallel | 1.0.0 |
--ultra | 5 fix plans, keep the best one | 2.13.0 |
--advice | A stronger model reviews at key checkpoints | 2.5.0 |
--skip-journal | Skips the automatic journal step | 2.9.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-fix: find the real cause of a bug and fix it at the root" on modernEngineer and apply it to this repo.
1. Call the content_get tool of the modernengineer MCP server with locale "en", slug "ak-fix". 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
- 22/10/2026
- Licence
- All rights reserved
- Slug
- ak-fix
