Optional cookies help us improve Palette. Cookie policy

Skip to main contentAnnouncing our €3M pre-seed
Book a founder callDownload

Working with lessons.md

Last updated:

lessons.md is a short, running list of what to do differently next time. The filename is a useful convention, not a built-in instruction that every agent reads automatically.

Link it from CLAUDE.md or AGENTS.md, or ask the agent to read it when the lesson matters. That gives future sessions a durable source for your corrections.

What goes in

Forward-looking corrections and durable preferences. Newest on top, one dated line each:

**2026-07-14** Draft investor updates in plain prose, not bullet lists.
**2026-07-09** Check the roster in accounts.md before prepping a call.
**2026-07-02** We say "customers", not "users".

Keep it to things worth remembering. A lesson earns a line when a teammate, or an agent doing this next month, would want to know.

Lessons, not history

lessons.md is what to do differently (rules, forward-looking). It is not a record of what happened, that is log.md. Keep the two apart: corrections in lessons, events in the log.

How to add one

Tell your agent, or let it offer.

  • "Add a lesson: keep subject lines under six words."
  • "That was wrong, note it so you don't do it again."

You can also ask the agent to suggest a lesson when it learns something durable, then review the line before it is saved.

Shared across your team

lessons.md lives in the workspace, not in one agent's memory, so it can be versioned and shared. Teammates can point their agents to the same lessons, but sharing the file does not make every agent read it automatically. Keep team-wide rules here, put personal preferences in your own file, and link the shared file from the instructions that should load it.

Put each lesson where it's true

Scope a lesson to the narrowest place it applies: a lesson about one customer goes in that account's folder, a lesson about how you write goes at the workspace root. A lesson that keeps coming up has earned a spot in your CLAUDE.md or AGENTS.md or a folder README, so promote it there.

Related