Skip to content
Ileen Docs

Lessons Learned

The Lessons Learned panel is your team’s persistent knowledge layer in Develop Mode. Instead of repeating the same instructions in every task prompt, you record them once — and every future AI agent task on that project automatically respects them.

Applies to: Develop Mode — Project Setup overview

Why Lessons Learned matters

AI coding agents are incredibly productive, but they don’t remember your team’s conventions between tasks. Without guidance, they make assumptions — sometimes the wrong ones. Lessons Learned bridges that gap: it gives the agents a permanent, curated set of rules, patterns, and constraints that shape every code change they propose.

Each lesson is tied to a specific repository in your project. When you submit a Task Plan or a Code Query, the agent sees the relevant lessons before writing any code.

Where to find it

  1. Go to Develop Mode and select a project.
  2. Open the Project Setup step (the first agent in the pipeline).
  3. Scroll below the repository list to the Lessons Learned accordion.
  4. Click the header to expand it.

The panel organises lessons by repository, with a counter badge showing how many lessons you have in total.

Adding a lesson

  1. Expand the Lessons Learned accordion.
  2. Find the repository you want to document and click the ＋ button next to its name.
  3. An inline text input appears. Write your lesson.
  4. Click ✓ to save, or ✕ to cancel.

A lesson is a single paragraph of guidance — there is no title/body split, no formatting, no categories. Just plain instructions the agent will read before every task. This simplicity is intentional: every word counts.

Editing and deleting

Every lesson has two inline controls:

  • Edit (pencil icon) — turns the lesson into an editable textarea. Confirm with ✓ or cancel with ✕.
  • Delete (trash icon) — prompts for confirmation, then removes the lesson permanently.

There is no undo for deletions. Changes take effect immediately — the next agent task on that project will see the updated lessons.

How lessons influence AI agents

Lessons are automatically injected into the context of every agent call for the project:

  • Run Task (Task Plans) — when you evaluate, discuss, or execute a task, the coding agent reads the lessons for every target repository. It uses them to align implementation choices, naming, and architectural patterns with your team’s standards.
  • Code Query — when you ask a question about your codebase, the agent includes the lessons as additional context for more accurate answers.
  • Prompt Engineer — when the Prompt Engineer helps refine a task description, it reads the lessons to suggest better prompts that respect your conventions.

This means you never repeat the same instruction. Add it once as a lesson, and every agent call on that project from that moment forward respects it.

Automatic lesson curation

Lessons are not only written by humans. After every Run Task execution, Ileen automatically reviews what happened and updates your lessons to keep them sharp:

  • Learns from mistakes. If the agent introduced a code quality issue, missed an edge case, or produced code that needed manual correction, a new lesson may be added automatically so the same mistake doesn’t happen again.
  • Merges duplicates. If similar issues recur across tasks, Ileen unifies them into a single, stronger rule rather than cluttering the list.
  • Generalises patterns. When the same type of problem appears in different files or repos, the lesson is broadened to cover the pattern, not just the specific file where it first appeared.
  • Removes what’s obsolete. If a lesson references a file that no longer exists or a pattern that’s no longer relevant, it’s automatically removed.

What this looks like in practice

After a task where the agent hardcoded placeholder values instead of reading from environment variables, Ileen detects the issue and adds:

Never commit hardcoded placeholder values — read all secrets from environment variables via the shared config module.

On the very next task, the agent sees this lesson and reads secrets from the config module instead of hardcoding values. No human had to write that lesson — the platform learned it from experience.

The more you use Ileen, the better it gets

Every task execution makes future tasks smarter. Human-authored lessons set the baseline. Automatic curation keeps them current and never stale. Over time, the lesson set becomes a high-signal knowledge base that reflects what your team has actually learned from real coding sessions — not just what you intended to document.

When to add a lesson

SituationExample lesson
After a bug fixNever use .delete() on QuerySets — use .update(is_active=False) to soft-delete records
Establishing conventionsAll new endpoints must include OpenAPI annotations with request/response schemas
Performance improvementUse select_related('customer', 'items__product') when listing orders — the listing endpoint must never trigger N+1 queries
Module boundariesThe payment module under billing/ is owned by the finance team — do not modify it
Data rulesAll datetimes must be stored as UTC and converted at the presentation layer
Security patternsEnvironment variables must be read via the shared config module — never use process.env directly
Testing standardsUse pytest-mock for Redis calls; tests must not require a running Redis instance
API designAll list endpoints must support ?search= for fuzzy text search across name/email fields

The key is specificity. A lesson like “write good code” is useless. A lesson like the examples above is actionable, checkable, and prevents real mistakes.

When NOT to add a lesson

Don’t use lessons for things the agent can already see:

  • Code that already exists in the repository — the agent reads your full codebase before every task. Don’t duplicate what’s already there.
  • Standard language/framework conventions — the agent knows that Python uses snake_case and React uses PascalCase for components.
  • One-off task instructions — if it only applies to today’s task, put it in the task description, not in a lesson.

A good rule of thumb: if you’d put it in a team CONTRIBUTING.md or an onboarding document, it belongs as a lesson.

Collaboration

All project collaborators (Editors) can view, add, edit, and delete lessons. Lessons are a shared team resource — not a private notebook. Any team member can contribute their insights, and everyone’s agent tasks benefit from the collective knowledge.

Lessons are per-project and never shared across different projects, even if they share the same repositories.

Tips for effective lessons

  • One topic per lesson. Split unrelated conventions into separate entries.
  • Keep lessons current. If a convention changes, edit or delete the old lesson immediately — stale guidance is worse than no guidance.
  • Write for an unfamiliar developer. The agent reads the lesson without your context. Be explicit about what, where, and why.
  • Use file paths. Use the shared RedisClient from src/lib/redis.ts is better than Use the existing Redis client.
  • Review after major refactors. After restructuring a module, check that your lessons still reference the correct files and patterns.

The resizable panel

The Lessons Learned body is vertically resizable — drag the handle at the bottom of the panel to expand it from 100px up to 600px. This is useful when you have many lessons across several repositories.