A structured markdown syntax for iterating on documents with Claude AI
Deep dive on the ==text(TOKEN)== syntax - marking specific text for feedback.
==highlighted text(TOKEN)==
The double equals wrap the text AND the token. The token in parentheses links to comments.
Important: Token goes INSIDE the highlight:
==text(TOKEN)== - correct (token inside)==text==(TOKEN) - wrong (token outside)Never nest highlights:
==outer ==inner(X)== (Y)== - invalid, will break parsingHighlights solve the “which one?” problem. When you have multiple items to comment on:
# Without highlights - ambiguous
Uses PostgreSQL with Redis on AWS.
%% Change the database %% ← Which one? PostgreSQL? Redis?
# With highlights - precise
Uses ==PostgreSQL(DB)== with ==Redis(CACHE)== on ==AWS(DEPLOY)==.
%%(DB) Switch to SQLite for v1 %%
%%(CACHE) Keep Redis %%
%%(DEPLOY) Consider DigitalOcean %%
For quick markup:
==item one(1)== ==item two(2)== ==item three(3)==
%%(1) Comment %%
%%(2) Comment %%
%%(3) Comment %%
For clarity in complex documents:
==PostgreSQL(DATABASE)==
==Redis(CACHE)==
==Kubernetes(DEPLOYMENT)==
Common pattern - short but meaningful:
==session timeout(AUTH)==
==rate limiting(PERF)==
==input validation(SEC)==
Use dashes for related items:
==PostgreSQL(DB-1)==
==MySQL(DB-2)==
==MongoDB(DB-3)==
%%(DB-1) Best for relational data %%
%%(DB-2) Also good, but PostgreSQL preferred %%
%%(DB-3) NO: Not suitable for this use case %%
Comments reference tokens with %%(TOKEN):
The API uses ==REST(STYLE)== with ==JSON(FORMAT)==.
%%(STYLE) Consider GraphQL %%
%%(FORMAT) APPROVED %%
Claude responds to each:
%%(STYLE) Consider GraphQL %%
•%%>Good point! Added GraphQL endpoint for complex queries.
REST remains default for simplicity. <%%•
%%(FORMAT) APPROVED %%
•%%>JSON confirmed! <%%•
When you have only one highlight nearby, use *:
The session timeout is ==15 minutes==.
%% * Change to 30 minutes %%
The * means “the highlighted text above.” Use this when there’s no ambiguity.
Each TOKEN should be unique within a document. If you need to comment on multiple related items, use numbered or suffixed tokens:
The ==primary database(DB-1)== stores user data.
Later, the ==backup database(DB-2)== syncs hourly.
%%(DB-1) Use PostgreSQL %%
%%(DB-2) Use PostgreSQL replica %%
If Claude sees %%(TOKEN) but no matching ==...(TOKEN)==, it will ask for clarification.
## Dependencies
- ==Vue 3(FRAMEWORK)==
- ==Pinia(STATE)==
- ==Tailwind(CSS)==
%%(FRAMEWORK) APPROVED %%
%%(STATE) ?: Vuex instead? %%
%%(CSS) Consider plain CSS for smaller bundle %%
| Feature | Status |
|---------|--------|
| ==Auth(F1)== | Done |
| ==Payments(F2)== | WIP |
| ==Admin(F3)== | Planned |
%%(F1) APPROVED %%
%%(F2) Needs security review %%
%%(F3) Move to v2 %%
Highlights don’t work inside code blocks. Comment separately:
```javascript
const timeout = 15; // AUTH
%%(AUTH) Increase timeout to 30 %%
## After Cleanup
Highlights become plain text. The markup is removed but content stays:
**Before cleanup:**
```markdown
Uses ==PostgreSQL(DB)== for data storage.
After cleanup:
Uses PostgreSQL for data storage.
Pick a naming style and stick with it:
# Consistent - all abbreviations
==...(DB)== ==...(API)== ==...(AUTH)== ==...(PERF)==
# Consistent - all numbers
==...(1)== ==...(2)== ==...(3)== ==...(4)==
# Inconsistent - mixed styles (avoid)
==...(DB)== ==...(2)== ==...(Authentication)== ==...(p)==
Only highlight text you need to comment on:
# Too much
==The== ==API== ==uses== ==REST==.
# Just right
The API uses ==REST(STYLE)==.
Use related tokens for connected decisions:
==Frontend(STACK-1)==: React
==Backend(STACK-2)==: Node.js
==Database(STACK-3)==: PostgreSQL
%%(STACK-1) APPROVED %%
%%(STACK-2) ?: Consider Go for performance? %%
%%(STACK-3) APPROVED %%