Skip to content
Ileen Docs

Lessons Learned

The Lessons Learned panel lets you record insights, conventions, and constraints for each repository in your project. Every lesson you add is automatically included as context when you launch a new Design or Develop agent task — so the AI respects the patterns and decisions you’ve already established.

Where to find it

The Lessons Learned panel is an accordion that appears in two places:

  • Develop Mode — alongside the repository list, below the codebase overview. Look for the Lessons Learned header on the project page.
  • Design Mode — on the Development Board, accessible after development has started.

Click the header to expand the panel. Each repository in your project has its own section, so you can keep lessons organised by codebase.

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 form appears with two fields:
    • Title — a short, descriptive label (e.g. “Use the existing Redis client”).
    • Content — the full guidance the AI should follow.
  4. Click Save to add the lesson. It appears immediately in the repository’s lesson list.

Editing and deleting lessons

Every lesson in the panel has inline controls:

  • Edit — click the edit icon (pencil) on any lesson to modify the title or content. Changes take effect immediately and will be included in the next agent task.
  • Delete — click the delete icon (trash) to remove a lesson permanently. The panel prompts you to confirm before deleting.

There is no undo for deletions, so double-check before confirming.

How lessons influence AI agents

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

  • Design Mode — when you chat with the AI Architect, Tech Leader, or Team Leader, the lessons you’ve recorded for each repository are included in the prompt. The agents use them to align architecture decisions, milestone plans, and task breakdowns with your established patterns.
  • Develop Mode — when you submit a task (via Run Task or a Task Plan), the lessons are included as part of the coding agent’s instructions. The agent reads them before writing any code and respects the constraints you’ve documented.

This means you don’t need to repeat the same instructions in every task prompt. Add them once as a lesson, and every future agent call on that project automatically includes them.

When to add a lesson

Good moments to add a lesson include:

  • After a bug fix — document why the bug happened and what pattern avoids it in the future.
  • When establishing conventions — for example, naming patterns, preferred libraries, or file organisation rules the team has agreed on.
  • After a performance improvement — record the optimisation approach so future changes don’t regress it.
  • When handling a constraint — such as “the payments module is owned by another team — do not modify it” or “all dates must be stored as UTC”.
  • After a security review — capture auth patterns, data-handling rules, or dependency policies.

Here are practical examples of useful lessons:

Always use the existing RedisClient singleton from src/lib/redis.ts
The payment module is handled by a third-party team — do not modify it
All new endpoints must include OpenAPI JSDoc annotations
Environment variables must be read via the shared config module — never use process.env directly
Database migrations must be backward-compatible — never drop a column in the same PR that adds its replacement

Privacy and visibility

Lessons are per-project — they belong to the project you add them to and are not shared across other projects in your account.

All collaborators on a project can view, add, edit, and delete lessons. If you invite a team member to a project, they’ll see the same lesson panel and can contribute their own insights. This makes lessons a shared team resource rather than a private notebook.

Lessons are never shared outside of the project or with Ileen support unless you explicitly choose to share them.

Tips for effective lessons

  • Be specific, not vague. Instead of “write good code”, say “use Zod for all input validation; never trust raw request bodies”.
  • Keep lessons up to date. If a convention changes, edit or remove the old lesson — stale guidance is worse than no guidance.
  • One topic per lesson. A lesson about database migrations shouldn’t also cover frontend routing. Split unrelated topics into separate lessons.
  • Use the title as a quick reference. Team members should be able to scan the lesson list and immediately understand the constraints in play.
  • Don’t duplicate what’s in the codebase. The AI already reads your source code. Use lessons for conventions, constraints, and decisions that aren’t obvious from the code alone.