Working with coding agents
Verdical and CLAUDE.md: what belongs where?
Keep repository instructions in CLAUDE.md. Give changing tasks, decisions and handoffs a place your agents can read and update.
Keep the instructions. Give changing work a home.
CLAUDE.md gives Claude Code persistent project instructions. Verdical holds issues, decisions and handoffs that agents read and update through a connection. You can use them together.
The useful question is where each kind of information belongs. A build command may stay valid for months. “The sandbox check is still missing” might change during the next session.
What goes where?
| Information | CLAUDE.md and repo files | Verdical |
|---|---|---|
| Project conventions | Keep build commands, code conventions and stable instructions close to the repo. | Store shared agent roles when you need them across projects. |
| Current work | A handoff file can hold the latest state; someone must maintain it. | Issues and work logs hold progress, remaining checks and the next step. |
| Decisions | Markdown decision records work well when you keep them organised. | Searchable decisions retain their reasons and recorded history. |
| GitHub status | A file reflects its last edit; agents can separately inspect GitHub. | Linked repository activity updates issue state. |
| Documentation changes | Review notes alongside code, manually or with your existing automation. | Documents linked to affected code paths are flagged for review. |
| Several products | Organise files and tell agents where to read them. | Keep records across products in one account. |
Claude Code already has memory.
Claude Code supports both instruction files and auto memory, and it can resume earlier sessions. Verdical is not required simply to retain context between conversations.
Those built-in options are worth trying first. See the official Claude Code memory guide and session workflow documentation.
Verdical adds a shared record of work: issues, explicit decisions, handoffs and repository-linked status. Its value depends on whether that record removes work you currently do yourself.
When files are enough.
- You work mainly in one repo and can find the relevant notes quickly.
- Resuming sessions or reading a short handoff gets you back to work.
- Your existing issue tracker and decision records stay useful without much cleanup.
In that situation, keep your setup. You can use the handoff example in our guide without connecting another service.
When Verdical is worth trying.
- You repeatedly explain the same decisions to new sessions.
- You move between repos or products and reconstruct their status each time.
- You maintain handoff files, issue updates and decision notes in several places.
Start with one active project. Connect the agent, record a real task and its decisions, then open a fresh session. Check whether it can retrieve the right next step without another briefing.
A practical setup using both.
# Ledgerly — Fernhill Labs (fictional example)
Use the existing form components for payment screens.
Run the relevant tests before reporting a change as checked.
Preserve entered values when validation fails.
Read the current task and its handoff before editing.
Record remaining checks and the next step before you stop.Keep those stable instructions in the repository. Store the card-error task, the reason for preserving input, the checks already run and the remaining sandbox check in Verdical. Tell the connected agent to read and update the relevant records.
Verdical relies on agents explicitly saving information; it does not capture every conversation automatically. Its GitHub status and document-review signals help keep records current, but do not replace testing or review.
During the private beta, access is by invitation and repository linking is assisted. Read how it works for setup and data handling, and current features for availability.