In short:
ak-docskeeps your project's docs andCLAUDE.md/AGENTS.mdaccurate, lean and backed by evidence. You pick the job with a subcommand, usually afterak-cookorak-fixfinishes a change that touches the docs. It does not write product code, and when nothing new needs recording, it writes nothing.
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 the project has no docs yet, when code just changed usage, config or architecture, when CLAUDE.md has grown large and the agent still gets things wrong, when the agent keeps repeating one kind of mistake, when you want to settle product principles, or when your docs site needs llms.txt. You do not need it when you only renamed an internal variable or changed something that does not affect usage: running update then would write nothing anyway.
flowchart LR
A["You call it directly"] --> B["ak-docs"]
C["ak-cook or ak-fix done, with a change that touches docs"] --> B
B --> D["Lean docs that point to code"]
B --> E["CLAUDE.md or AGENTS.md"]
B --> F["llms.txt and llms-full.txt"]
B --> G["Nothing new: writes nothing"]It follows 4 principles:
| Principle | Question | Example |
|---|---|---|
| Docs keep only why and where | Does this sentence belong in the docs? | "We chose Postgres because we need transactions across several tables" stays. "The createUser function takes an email and a password" is cut and replaced with one line pointing to the code file. When the design has real variants, for example two payment gateways sharing one interface, the docs record what both must preserve that the code cannot say, why the split sits at that interface, the options ruled out, and the cost accepted, then point the rest to the interface. A third gateway nobody has committed to is at most an open question, not a roadmap. |
| Agent context files are rules of behavior | Without this line, what specific thing would the agent get wrong? | "Use pnpm, not npm" stays. "This is an inventory management app" is cut, because the agent learns that by reading the repo. |
| No change is a correct result | Is there anything new and lasting to record this time? | You only renamed an internal variable. update edits no files, changes no dates, and does not reorder sections to look busy. |
| Routine fixes and fixes that need approval | Does it write on its own or ask you first? | A command in the docs points to a wrong path: it fixes that itself. Replacing a passage you wrote, changing something you once corrected, or widening access: it proposes first. Secret values are never written, whoever approves. |
The seven subcommands are init, update, summarize, agent-context, agents, philosophy and llms; agents and philosophy always wait for you to approve the diff. When it records how to get a credential, the docs follow the secret store you chose, it does not open .env files, and it never writes a secret value.
Sample prompt after a code change:
/ak-docs update The payments part of <app name> just moved from webhooks to polling.
Update the affected docs.
Constraints: do not touch unrelated docs.
--advice| Flag | What it is for | Since ak |
|---|---|---|
--advice | A stronger model advises what to keep, cut or reorder before writing | 2.7.0 |
--audit | You decide each change yourself, one question per decision | 2.7.0 |
--dry-run | agents only: see ranked signals, no rules proposed yet | 2.13.0 |
--source | agents only: look for extra signals in the code itself | 2.13.0 |
--preset classic | init only: use a fixed set of 7 docs file names | 2.16.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-docs: keep docs and agent context files accurate and lean" on modernEngineer and apply it to this repo.
1. Call the content_get tool of the modernengineer MCP server with locale "en", slug "ak-docs". 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-docs
