Session learnings

Reflect on the current coding session, identify reusable lessons, and persist them as AGENTS.md entries or new skills so future sessions avoid the same pitfalls.

Step 1: Identify learnings

Review the conversation for:

• •Errors that required multiple attempts to fix
• •Tooling surprises (e.g. auto-generated files, deprecated APIs)
• •Project-specific conventions that weren't obvious
• •Patterns that worked well and should be repeated

For each candidate learning, ask:

• •Is it already enforced? If a linter, type checker, or existing rule already catches it, it doesn't need documenting — the tool will teach the agent at runtime.
• •Is it project-specific? Generic best practices (e.g. "write tests") don't belong. Only capture knowledge an agent couldn't infer from the code alone.
• •Is it durable? Avoid time-sensitive notes. If something will change soon, skip it.

Step 2: Choose the right format

Guidelines for placement:

• •Subdirectory AGENTS.md files may only live at the first level under src/ (e.g. src/inngest/AGENTS.md, src/server/AGENTS.md). Never create one deeper than that (e.g. not src/inngest/importers/AGENTS.md).
• •If a learning is specific to a sub-area, place it in the nearest top-level src/ parent's AGENTS.md instead.
• •If an AGENTS.md already exists at the target level, append to it. Don't create a competing file.
• •If the learning is a multi-step process with decision points or templates, create a skill instead.
• •When creating a new AGENTS.md under src/, also create a CLAUDE.md symlink next to it (ln -s AGENTS.md CLAUDE.md).

Step 3: Write the entry

For AGENTS.md entries:

• •Use a descriptive ## heading
• •Keep it to 1-4 sentences. Be direct.
• •Include a short code example only if the correct pattern is non-obvious.
• •Don't repeat what linters or type checkers already enforce.

For new skills:

• •Follow the skill creation guidelines in ~/.cursor/skills-cursor/create-skill/SKILL.md
• •Place project skills in .ai/skills/

Step 4: Verify

• •Read the updated file back to confirm it merged cleanly with existing content.
• •Confirm no duplicate or contradictory entries exist in the same file.
• •If you created a new AGENTS.md, verify there isn't already one at that directory level.

Example

A session revealed that routeTree.gen.ts is auto-generated and shouldn't be manually regenerated. This is project-wide and not caught by any linter, so it belongs in the root AGENTS.md:

## TanStack Router route generation

The route tree (`src/routeTree.gen.ts`) is auto-generated by the TanStack Router Vite plugin. When you create a new route file under `src/routes/`, do **not** try to manually regenerate it with CLI commands. The plugin regenerates it automatically when the dev server is running or on the next build.

A session revealed that OpenAI Agents SDK requires all Zod fields to be required when strict: true. This is scoped to inngest, so it belongs in src/inngest/AGENTS.md — not the root, and not deeper like src/inngest/importers/AGENTS.md.