Alyson Docs

Using AI for Docs

How to use Claude Code, Cursor, and Codex to write and maintain documentation.

Owner: @adminStatus: stableLast verified: 5/18/2026

This is the harness. Read it once before you start documenting things with an AI agent.

Mental model

Documentation isn't a one-shot task — it's an extended, multi-session conversation between you and an agent that doesn't remember anything across sessions. To make that work, we rely on three tools:

  1. AGENTS.md — global instructions the agent reads on every session start.
  2. Slash commands — pre-written prompts for common workflows.
  3. The working/ scratchpad — the agent's persistent memory between sessions.

Every documentation task follows: open a scratchpad, run a slash command, iterate with the agent updating the scratchpad as it goes. If your context window fills up, start a new session, point it at the scratchpad, and it picks up where you left off.

Setup (one-time)

  1. Clone both repos as siblings: 
    ~/work/
├── alyson-docs/
└── alyson-backend/       (or whichever code repo you're documenting)
  2. Open your AI tool of choice in alyson-docs/.
  3. The tool will read AGENTS.md (Codex, Cursor) or CLAUDE.md (Claude Code) automatically.

Per-tool notes

Claude Code

  • Reads CLAUDE.md at session start (which imports AGENTS.md via @AGENTS.md).
  • Slash commands live in .claude/commands/ — invoke as /document-service, /document-feature, /qa-session.
  • Use cd ../alyson-backend (or similar) to give the agent access to a code repo within the same session.

Cursor

  • Reads .cursor/rules/main.mdc which references AGENTS.md.
  • For "slash commands," paste the relevant file from .claude/commands/ into the chat as a system prompt, or use Cursor's saved-prompts feature.
  • Open both repos in the same workspace (File → Add Folder to Workspace).

Codex (OpenAI)

  • Reads AGENTS.md natively.
  • For slash-command-style workflows, copy the relevant .claude/commands/*.md content into the initial prompt.

GitHub Copilot

  • Reads .github/copilot-instructions.md.
  • Best used for inline assist while editing, not for full doc-drafting sessions.

The scratchpad pattern

Every documentation task starts by creating a file in working/:

working/
├── README.md                          (committed; explains the convention)
├── experiment-manager-intake.md       (your brain-dump)
├── experiment-manager-progress.md     (the agent's working memory)
└── backend-prepop-api-progress.md

A *-progress.md file has this structure:

# <Task name> — Progress

## Goal
What we're trying to produce.

## Status
- [x] Read source files at <paths>
- [x] Drafted Overview section
- [ ] Drafted API Reference section — IN PROGRESS
- [ ] Drafted Deployment section
- [ ] Drafted Monitoring section
- [ ] Moved to docs/20-services/...

## Open questions for the user
1. ...
2. ...

## Decisions made this session
- ...

## Next steps
1. ...
2. ...

## Notes / context the next session needs
- ...

When you start a new session with full context lost, your first message to the agent is:

Read working/<task>-progress.md and pick up where the previous session left off.

The agent reads the file, restores context, and continues. The agent is required to update this file after every meaningful step — this is in AGENTS.md.

Slash commands available

CommandWhen to use
/document-service <name>Documenting a service/microservice from scratch
/document-feature <name>Documenting a product feature from scratch
/qa-session <topic>Extracting context from you via Q&A when you don't have a written intake

See .claude/commands/ for the actual prompts. They're plain Markdown files — read them.

When to commit the scratchpad

  • During a multi-session task: yes, commit progress.md so it's safe across machines.
  • After the doc lands in docs/: archive or delete the scratchpad.
  • The working/ folder is intentionally committed (not gitignored) for this reason.

Anti-patterns

  • Don't let the agent invent context. If it doesn't know something, it should ask, not guess. AGENTS.md instructs it to do this.
  • Don't try to do it all in one session. Use the scratchpad.
  • Don't skip the intake. Code-reading alone produces shallow docs.
  • Don't accept a draft you haven't read. AI hallucinates. Read every section.