Ai Coding Agent Setup

AI Coding Agent Setup

Configure AI agents to deeply understand a codebase and continuously improve as the project grows. This skill covers the three-layer architecture: AGENTS.md for project identity, agent skills for packaged workflows, and MCP servers for live tool access — plus self-improvement strategies to prevent context rot.

Quick Reference Table

---

Orchestration Protocol

Phase 1 — Classify the Request

Determine which layer the user needs help with:

• "Set up AI for my project" → start with agents-md-guide.md, then assess if skills and MCP are needed
• "AI keeps making the same mistake" → self-improvement-patterns.md (feedback loops section)
• "AI can't navigate my code / doesn't understand the structure" → mcp-codebase-tools.md
• "How do I package this workflow for AI reuse?" → agent-skills-architecture.md
• "Agent ignores my conventions" → agents-md-guide.md (conventions and enforcement section)

Phase 2 — Select Resource

Load the relevant resource file from the table above. Most setups require agents-md-guide.md as the foundation, with other resources added on top.

Phase 3 — Execute

Follow the specific guidance in the loaded resource. Output actionable file content (AGENTS.md, SKILL.md, mcp.json) — not just advice.

---

Common Task Workflows

Workflow 1: New Project AI Setup (15 minutes)

1. Load resources/agents-md-guide.md → create AGENTS.md at repo root using the template 2. Add project overview, build commands, test instructions, code conventions 3. Configure .vscode/mcp.json with at minimum the Bifrost server (see mcp-codebase-tools.md) 4. If the project has complex, repeatable workflows → package them as skills (see agent-skills-architecture.md) 5. Commit all AI configuration files to version control alongside the codebase

Workflow 2: AGENTS.md for an Existing Repo

1. Load resources/agents-md-guide.md 2. Audit the existing README.md for technical content that belongs in AGENTS.md 3. Extract: build commands, test scripts, folder structure map, conventions → move to AGENTS.md 4. For monorepos: create root AGENTS.md + sub-directory AGENTS.md files for each package 5. Add a "pointer" to CLAUDE.md or copilot-instructions.md referencing AGENTS.md

Workflow 3: Preventing Agent Mistakes from Recurring

1. Identify the pattern: did the agent use a wrong pattern/file/command? 2. Load resources/self-improvement-patterns.md 3. Update the relevant AGENTS.md section with an explicit correction 4. If the mistake is workflow-specific → update or create a skill (agent-skills-architecture.md) 5. Test: ask the agent to perform the same task; verify it now follows the corrected instruction

Workflow 4: Giving Agents Deep Code Navigation

1. Load resources/mcp-codebase-tools.md 2. Install Bifrost VS Code extension (provides call hierarchy, find usages, go-to-definition) 3. Add server config to .vscode/mcp.json 4. For semantic search → configure a vector-store MCP server (Qdrant or Azure AI Search) 5. Document MCP tool names in AGENTS.md so the agent knows when to use them

Workflow 5: Self-Improving Agent Configuration

1. After each significant debugging session, ask the agent: "What should we add to AGENTS.md to prevent this?" 2. Review proposed update → approve and commit 3. Monthly: use a "review" prompt against self-improvement-patterns.md to audit all config files 4. Over time: stale instructions become "context rot" — prune or update them proactively

---

Resource Summaries

---

Best Practices

• Identity vs. Capability: Use AGENTS.md for static project rules (identity); use skills for dynamic, executable workflows (capability). Do not put workflow logic in AGENTS.md.
• Commit AI config to version control: AGENTS.md, skills, and mcp.json are first-class project files — track them in git alongside code.
• Hierarchical AGENTS.md for monorepos: Root file holds global rules; sub-directory files override for local packages. Closest file wins.
• Treat agent mistakes as documentation bugs: Every repeated agent error is a missing or incorrect instruction in AGENTS.md or a skill. Fix the docs, not just the output.
• Pointer pattern: In CLAUDE.md write Read @AGENTS.md — avoids duplication across tool-specific instruction files.
• Progressive disclosure in skills: Keep SKILL.md under 5,000 words; move heavy reference content to resources/ files loaded only when needed.
• Name MCP tool names explicitly: Include exact MCP tool names in AGENTS.md so agents know which tools to invoke for code navigation tasks.

---

External References

• AGENTS.md Open Standard — AAIF
• Anthropic Skills Documentation
• Model Context Protocol Specification
• Bifrost VS Code MCP Extension
• GitHub MCP Server

Agent Skills Architecture for Project-Specific Workflows

Agent skills package specialized, reusable workflows as SKILL.md-based modules. While AGENTS.md defines what the project is, skills define what the agent can do within it. This resource covers how to design skills for your project's repeatable tasks.

---

Overview: Identity vs. Capability

Skills are loaded via progressive disclosure:

• Level 1 (always in context): metadata only (~100 tokens per skill)
• Level 2 (loaded when triggered): full SKILL.md instructions
• Level 3 (loaded as needed): scripts, reference files, assets

---

When to Create a Skill for Your Project

Create a project-specific skill when:

• The same multi-step workflow is repeated frequently (e.g., "add a new feature module")
• Architectural rules are complex enough to warrant dedicated instructions
• The workflow involves tool coordination (MCP + file edits + test runs)
• Agent mistakes follow a pattern that hints at missing procedural knowledge

Do not create a skill for:

• One-off tasks unlikely to recur
• Simple conventions already in AGENTS.md
• Straightforward single-step operations

---

Skill Structure for Project Workflows

.claude/skills/
├── add-feature/
│   ├── SKILL.md               # Trigger phrases + step-by-step workflow
│   └── resources/
│       ├── feature-template.md    # Template showing expected file layout
│       └── conventions.md         # Architecture-specific rules
│
├── database-migration/
│   ├── SKILL.md
│   └── scripts/
│       └── generate-migration.py  # Deterministic migration generation
│
└── deploy-staging/
    ├── SKILL.md
    └── resources/
        └── checklist.md           # Pre-deploy validation steps

Skills can live in:

• .claude/skills/ — project-level (committed to repo)
• ~/.claude/skills/ — personal/global (available across all projects)

---

Writing Effective Trigger Phrases in SKILL.md

The description field in SKILL.md frontmatter determines when the skill loads. Per the AAIF spec, it is pre-loaded as lightweight metadata (~100 tokens) so the agent can decide relevance.

Effective Description Pattern

[What it does] + [When to use it] + [Exact trigger phrases]

Example — good:

description: Scaffolds a new REST API endpoint in this project following our
  layered architecture (router → service → repository). Use when asked to
  "add an endpoint", "create a route", or "add an API for [feature]".
  Generates controller, service, repository, and test files in the correct
  directories with the project's naming conventions pre-applied.

Example — too vague:

description: Helps with API development.

Preventing Over-Triggering

Add explicit exclusions to prevent the skill loading for unrelated tasks:

description: ... Do NOT use for frontend component creation (use the
  add-component skill instead) or for database migrations (use
  database-migration skill).

---

Structuring SKILL.md for a Project Workflow

Follow this template for project-specific skills:

---
name: [project-name]-[workflow]
description: [What + When + Triggers + Exclusions]
metadata:
  project: [project-name]
  version: 1.0.0
---

# [Workflow Name]

Brief description of what this workflow produces.

## Critical

[Any must-follow rules — put them first, use this section for non-negotiables]

## Steps

1. [Step 1 — specific, actionable]
2. [Step 2]
3. [Step 3 — including: run `[test command]` to validate]

## File Locations

- New files go in: `[path]/`
- Naming pattern: `[pattern]`
- Import from: `[path]` using `[alias]`

## Conventions for This Workflow

- [Specific rule 1]
- [Specific rule 2]

## Validation Checklist

Before marking complete:
- [ ] Tests pass: `[command]`
- [ ] Types check: `[command]`  
- [ ] No lint errors: `[command]`

---

Example: "Add Feature Module" Skill

For a project using a feature-based folder structure:

---
name: add-feature-module
description: Creates a new feature module in the project following the
  feature-slice architecture. Use when asked to "add a feature",
  "create a new module", or "scaffold [feature-name]". Creates the
  full directory structure, index barrel, component, hook, and test files.
  Do NOT use for standalone utility functions or API-only changes.
---

# Add Feature Module

Creates a complete feature slice: component, hook, types, tests, and barrel.

## Critical

All new feature modules MUST be placed in `src/features/[feature-name]/`.
Never place feature logic directly in `src/components/` or `src/pages/`.

## Steps

1. Create directory: `src/features/[name]/`
2. Create `src/features/[name]/index.ts` (barrel file, re-exports public API only)
3. Create `src/features/[name]/[Name].tsx` (main component — named export)
4. Create `src/features/[name]/use[Name].ts` (hook for business logic)
5. Create `src/features/[name]/[name].types.ts` (TypeScript types)
6. Create `src/features/[name]/[name].test.tsx` (Vitest + Testing Library)
7. Run `pnpm typecheck && pnpm test` to validate

## Naming Conventions

- Directory: lowercase kebab-case (`user-profile`)
- Component file: PascalCase (`UserProfile.tsx`)
- Hook file: camelCase with `use` prefix (`useUserProfile.ts`)
- Types file: lowercase with `.types.ts` suffix

## What NOT to do

- Do not create `default` exports (use named exports everywhere)
- Do not import directly from sub-files — always go through the barrel (`index.ts`)
- Do not add styling inline — use the `[Name].module.css` file pattern

---

Skills for Architecture Migration

When the team is migrating from one pattern to another, a skill ensures consistency:

---
name: migrate-to-react-query
description: Migrates a component from local useState/useEffect data fetching
  to TanStack Query (React Query). Use when asked to "migrate data fetching",
  "convert to React Query", or "refactor [component] to use TanStack".
---

# Migrate Component to TanStack Query

## Steps

1. Install check: verify `@tanstack/react-query` in package.json
2. Identify the fetch pattern to replace (useEffect + useState)
3. Create a query key constant in `lib/query-keys.ts`
4. Replace the useState/useEffect with `useQuery(queryKey, fetchFn)`
5. Map loading/error/data states to the component's existing UI
6. Add the query to `QueryClient` prefetching if it's a page-level fetch
7. Run `pnpm test [component]` to confirm behaviour unchanged

## Key Patterns in This Codebase

- Query keys defined in `lib/query-keys.ts` (centralized)
- Query functions defined in `lib/api/` (not inline in components)
- Error boundaries in `app/error.tsx` handle React Query errors globally

---

Meta-Skills: Skills that Create Skills

A meta-skill instructs the agent to observe a successful session and write a new skill to automate it:

---
name: capture-workflow
description: After successfully completing a complex, repeatable task, use
  this skill to capture the workflow as a new SKILL.md. Use when asked to
  "save this workflow", "create a skill for this", or "automate what we just did".
---

# Capture Workflow as Skill

## Steps

1. Review the current session for the repeatable steps just performed
2. Identify: trigger phrases, step order, file locations, validation commands
3. Run: `python scripts/init_skill.py [name] --path .claude/skills/`
4. Write SKILL.md with:
   - Precise description with trigger phrases from this session
   - Step-by-step instructions (imperative, not suggestions)
   - Exact commands used
   - Validation checklist
5. Test by asking: "Would you use [skill-name] to do [task]?" — verify it
   loads correctly
6. Commit to version control

---

Deployment: Making Skills Available to the Team

AGENTS.md Guide

AGENTS.md is an open-standard file (governed by the Agentic AI Foundation / Linux Foundation) that serves as a "README for agents." While README.md is written for human contributors, AGENTS.md provides the precise technical context AI coding agents need to operate autonomously: build steps, testing protocols, architectural constraints, and conventions.

---

Recommended Sections

1. Project Overview

A concise technical summary — not marketing copy. Include:

• Primary tech stack (languages, frameworks, runtimes)
• Core architectural pattern (monolith, microservices, monorepo, etc.)
• Key directories and their purpose
• Any unusual or non-standard choices

Example:

## Project Overview

Full-stack web application built with Next.js 15 (App Router), TypeScript strict mode,
and a PostgreSQL database accessed via Drizzle ORM. REST API routes in `app/api/`.
Frontend components use shadcn/ui. Authentication via NextAuth.js.

Key directories:
- `app/` — Next.js App Router pages and API routes
- `lib/` — Shared utilities, database client, auth helpers
- `components/` — Reusable UI components (shadcn/ui based)
- `db/` — Drizzle schema, migrations
- `tests/` — Vitest unit + integration tests

2. Setup & Build Commands

Exact, copy-pasteable commands. Agents run these literally.

## Setup & Build

Install dependencies:
  pnpm install

Start development server:
  pnpm dev                  # runs on http://localhost:3000

Run database migrations:
  pnpm db:migrate

Build for production:
  pnpm build

3. Testing Instructions

Include linting, type-checking, and unit/integration test commands. Specify what agents must run before committing.

## Testing

Run all tests:
  pnpm test

Run tests in watch mode:
  pnpm test:watch

Type-check without building:
  pnpm typecheck

Lint:
  pnpm lint

IMPORTANT: Always run `pnpm typecheck && pnpm test` before marking a task complete.

4. Code Style & Conventions

The most valuable section for eliminating repeated mistakes. Be specific.

## Code Style & Conventions

- TypeScript strict mode is enabled — never use `any`
- Use `type` not `interface` for object shapes
- Functional components only — no class components
- All imports use path aliases (`@/lib/...` not relative `../../lib/...`)
- Single quotes, no semicolons (enforced by ESLint/Prettier)
- Use named exports, not default exports (except page components)
- Database queries go in `lib/db/` — never inline SQL in components
- Environment variables accessed only through `lib/env.ts` (validated at startup)

5. Architecture & Constraints

Document non-obvious decisions and hard constraints.

## Architecture Constraints

- This is a multi-tenant SaaS — always filter queries by `organizationId`
- Never expose user PII in API responses; strip before returning
- All external API calls go through `lib/api-client.ts` (centralizes auth headers)
- Background jobs use BullMQ — do not use `setTimeout` for deferred work
- Feature flags checked via `lib/flags.ts` — do not hardcode feature availability

6. Security Considerations

Make implicit security rules explicit.

## Security

- Never log request bodies or database query results (may contain PII)
- API routes validate JWT via `lib/auth/validate.ts` — do not skip this
- All user-controlled strings are escaped before DB insertion (Drizzle handles this)
- `NEXT_PUBLIC_*` env vars are exposed to the browser — never put secrets there
- Dependency updates: run `pnpm audit` before merging security-related PRs

7. Operational Context

Commit message format, PR conventions, branch naming, etc.

## Operational Context

Commit format: `type(scope): description` (Conventional Commits)
  - feat(auth): add OAuth2 provider
  - fix(api): handle null user response
  - chore(deps): update Next.js to 15.2

Branch naming: `feature/short-description`, `fix/issue-number`, `chore/task-name`

Do not commit directly to `main` — use PRs with at least one reviewer.

---

Hierarchical Discovery in Monorepos

AGENTS.md supports nested files to avoid bloating a single root file and to provide scoped instructions per package.

Resolution Rules

1. Agents discover instructions by searching from the current file's directory upward to the repo root 2. The closest AGENTS.md takes precedence (most-specific wins) 3. Agents typically load all AGENTS.md files along the path and merge them, with closer files overriding global rules

Recommended Structure

repo/
├── AGENTS.md                          # Global: team conventions, CI, git rules
├── packages/
│   ├── frontend/
│   │   └── AGENTS.md                  # Overrides: React/Next.js specifics
│   ├── backend/
│   │   └── AGENTS.md                  # Overrides: Go/API specifics
│   └── shared/
│       └── AGENTS.md                  # Overrides: shared library rules
└── infra/
    └── AGENTS.md                      # Overrides: Terraform/Pulumi specifics

The root AGENTS.md defines baseline rules. Subdirectory files add or override for their scope. Example root entry:

## Root Conventions
Use spaces for indentation (2 spaces). All packages must have tests.

And the frontend override:

## Frontend-Specific Build

Install all packages from repo root: `pnpm install`
Start only frontend: `pnpm --filter @repo/frontend dev`
Run frontend tests: `pnpm --filter @repo/frontend test`

---

Comparison: AGENTS.md vs. CLAUDE.md vs. copilot-instructions.md

Convergence Trend (2026)

The industry is converging on AGENTS.md as the unified baseline. As of early 2026, it is supported by Cursor, Codex, Gemini CLI, and Claude Code.

The recommended pattern for multi-tool repos:

1. Write all project context into AGENTS.md (the single source of truth) 2. Create CLAUDE.md containing only: Read @AGENTS.md 3. Create .github/copilot-instructions.md containing only: See AGENTS.md for project context

This avoids duplicating project knowledge across tool-specific files.

---

AGENTS.md Template

Copy and customize this template for any project:

# AGENTS.md — [Project Name]

## Project Overview

[One paragraph: tech stack, architecture, purpose]

Key directories:
- `src/` — [purpose]
- `tests/` — [purpose]

## Setup & Build

Install dependencies:
  [command]

Start development:
  [command]

## Testing

Run all tests:
  [command]

IMPORTANT: Always run [test command] before marking work complete.

## Code Style & Conventions

- [Convention 1]
- [Convention 2]
- [Convention 3]

## Architecture Constraints

- [Constraint 1]
- [Constraint 2]

## Security

- [Security rule 1]
- [Security rule 2]

## Operational Context

Commit format: [format]
Branch naming: [pattern]

---

Common AGENTS.md Mistakes to Avoid

MCP Servers for Codebase Navigation

Model Context Protocol (MCP) gives AI agents live, dynamic access to your IDE, codebase, and infrastructure — beyond what static files can provide. This resource covers the key MCP servers for code navigation, semantic search, and developer tooling.

---

Overview: Why MCP for Codebase Understanding

Static files (AGENTS.md, skills) give agents context about how the project works. MCP gives agents tools to explore the living codebase — finding usages, navigating call hierarchies, checking diagnostics, and querying databases.

---

Primary MCP Servers

1. Bifrost — IDE Language Server for Agents

The highest-value MCP server for codebase navigation. Bifrost is a VS Code extension that exposes the IDE's Language Server Protocol (LSP) capabilities to LLMs via MCP.

Install: Search "Bifrost" in VS Code Extensions, or ext install bifrost.bifrost-mcp

Configuration (.vscode/mcp.json):

{
  "servers": {
    "bifrost": {
      "type": "stdio",
      "command": "node",
      "args": ["${userHome}/.vscode/extensions/bifrost.bifrost-mcp-*/dist/server.js"]
    }
  }
}

Available Tools:

Add to AGENTS.md:

## MCP Tools Available

Code navigation (via Bifrost MCP):
- `find_usages` — find all references to a symbol
- `get_call_hierarchy` — trace calls to/from a function
- `go_to_definition` — navigate to a definition
- `get_diagnostics` — check for compilation errors

Use these tools instead of grepping source files for symbol references.

---

2. vscode-mcp-server — VS Code Control and File Analysis

Open-source server that turns a local VS Code instance into an MCP server. Complements Bifrost with additional file editing, terminal, and symbol tools.

Install: npx @vscode/mcp-server

Configuration (.vscode/mcp.json):

{
  "servers": {
    "vscode": {
      "type": "stdio",
      "command": "npx",
      "args": ["@vscode/mcp-server"]
    }
  }
}

Key Tools:

---

3. GitHub MCP Server — Remote Repository Context

For exploring code that isn't locally checked out, or for cross-repository searches.

Install: npx @github/mcp-server

Configuration (.vscode/mcp.json):

{
  "servers": {
    "github": {
      "type": "stdio",
      "command": "npx",
      "args": ["@github/mcp-server"],
      "env": {
        "GITHUB_TOKEN": "${env:GITHUB_TOKEN}"
      }
    }
  }
}

Key Tools:

---

4. Semantic Search via Vector Store MCP

For natural-language queries over large codebases or documentation, connect a vector store.

Option A: Qdrant (self-hosted)

{
  "servers": {
    "qdrant": {
      "type": "stdio",
      "command": "npx",
      "args": ["qdrant-mcp-server"],
      "env": {
        "QDRANT_URL": "http://localhost:6333",
        "COLLECTION_NAME": "codebase"
      }
    }
  }
}

Workflow: 1. Index codebase: python scripts/index-codebase.py --collection codebase 2. Query: agent calls search("How does auth work?") → returns relevant code chunks

Option B: Azure AI Search (cloud)

{
  "servers": {
    "azure-search": {
      "type": "stdio",
      "command": "npx",
      "args": ["azure-ai-search-mcp"],
      "env": {
        "AZURE_SEARCH_ENDPOINT": "${env:AZURE_SEARCH_ENDPOINT}",
        "AZURE_SEARCH_API_KEY": "${env:AZURE_SEARCH_API_KEY}",
        "INDEX_NAME": "codebase-index"
      }
    }
  }
}

---

5. Database MCP Server — Live Schema Access

Prevent agents from guessing at database schemas by giving them direct query access.

Configuration example (PostgreSQL):

{
  "servers": {
    "postgres": {
      "type": "stdio",
      "command": "npx",
      "args": ["@modelcontextprotocol/server-postgres"],
      "env": {
        "DATABASE_URL": "${env:DATABASE_URL}"
      }
    }
  }
}

Agents can call:

• list_tables — enumerate all tables
• describe_table — columns, types, constraints for a table
• query — run a SELECT query (read-only by default)

Security note: Use a read-only database user for the MCP server connection. Never point MCP at a production database with write credentials.

---

Full mcp.json Template

Place this at .vscode/mcp.json in your project root:

{
  "servers": {
    "bifrost": {
      "type": "stdio",
      "command": "node",
      "args": ["${userHome}/.vscode/extensions/bifrost.bifrost-mcp-*/dist/server.js"],
      "description": "LSP-powered code navigation (find usages, call hierarchy, diagnostics)"
    },
    "github": {
      "type": "stdio",
      "command": "npx",
      "args": ["@github/mcp-server"],
      "env": {
        "GITHUB_TOKEN": "${env:GITHUB_TOKEN}"
      },
      "description": "GitHub code search and repository access"
    }
  }
}

Add other servers (vscode, postgres, qdrant) as needed.

---

Tool Selection Guide

When should agents use which tool?

Document this guide in AGENTS.md so agents know which tool to reach for.

---

Troubleshooting MCP Configuration

Self-Improvement Patterns for AI Agents

Agent configurations become stale over time — a phenomenon called "context rot." This resource covers strategies for keeping AI context accurate, establishing feedback loops, preventing context window poisoning, and building living documentation that improves with the project.

---

The Problem: Context Rot

Context rot occurs when:

• AGENTS.md instructions describe outdated conventions or deleted files
• Skills contain stale commands that no longer match the codebase
• The agent follows superseded patterns because no one updated the docs
• Context windows fill with conflicting instructions, reducing signal quality

Left unaddressed, context rot causes agents to regress — making mistakes that were previously corrected.

---

Strategy 1: Treat Agent Mistakes as Documentation Bugs

Every repeated agent error signals a gap or inaccuracy in AGENTS.md or a skill.

Feedback Loop Protocol

When an agent makes a mistake:

1. Identify — Was it a wrong command, wrong pattern, or wrong file path? 2. Locate — Which file (AGENTS.md or a skill) should have prevented it? 3. Update — Add an explicit instruction that corrects the behaviour 4. Test — Repeat the original task; verify the agent now follows the correction 5. Commit — Treat the doc update as a code fix; add it to the PR or commit

Example:

Agent made mistake: Used `npm install` instead of `pnpm install`
Fix: Added to AGENTS.md under ## Setup:
  "Package manager: pnpm (NOT npm or yarn). Always use `pnpm install`.
   Running `npm install` will corrupt the lockfile."

---

Strategy 2: End-of-Session Improvement Prompts

After completing a complex task, explicitly ask the agent to propose documentation improvements.

Prompt Templates

After debugging:

Based on the debugging session we just completed, what should we add to 
AGENTS.md to prevent this class of error in future sessions?

After implementing a new pattern:

We just added [feature/pattern]. Update AGENTS.md to document this new
convention so future agents (and teammates) understand it.

After a failed refactor attempt:

The approach we first tried didn't work because [reason]. Add a note to
AGENTS.md or the relevant skill so agents don't repeat this mistake.

Weekly/monthly review:

Review AGENTS.md and all skills in .claude/skills/. Identify any instructions
that are outdated, incorrect, or missing based on what you know about the
current codebase. List proposed changes.

---

Strategy 3: Progressive Disclosure to Prevent Context Overload

Loading everything into context simultaneously causes "context collapse" — the agent loses coherence as the window fills.

Tiered Loading Architecture

Design for this in AGENTS.md:

• Keep AGENTS.md under 500 lines — move detailed docs to skills and references
• Use skills instead of long AGENTS.md appendices for workflow procedures
• Write skill descriptions that are specific enough to trigger only when relevant

Context Compression Checkpoints

For long sessions, periodically compact context:

Provide a concise summary of what we've accomplished, the key decisions made,
and importantly, any updated understanding of the codebase architecture. 
I'll use this as a checkpoint if the context window fills.

---

Strategy 4: Memory Architecture for Long-Lived Projects

For projects maintained over months/years, structure persistent memory across layers:

Memory Tiers

Short-term memory:   Active conversation context (message buffer)
                     ↓ fades at session end
Core memory:         AGENTS.md — stable conventions and project identity
                     ↓ persists across sessions
Skill memory:        .claude/skills/ — executable workflows and patterns
                     ↓ persists across sessions
Archival memory:     Vector store (via MCP) — searchable history of decisions
                     ↓ persists; retrieved on demand

Practical Implementation

1. Core memory → Maintain in AGENTS.md (version-controlled, human-readable) 2. Skill memory → Commit skills to .claude/skills/ in the repo 3. Archival memory → For decision rationale, use an Architecture Decision Record (ADR) folder:

docs/
└── decisions/
    ├── 001-chose-drizzle-over-prisma.md
    ├── 002-feature-slice-architecture.md
    └── 003-tanstack-query-for-server-state.md

Reference ADRs in AGENTS.md:

## Architecture Decisions

Key architectural decisions are documented in `docs/decisions/`.
Consult these before proposing changes to core patterns.
Notable decisions:
- #002 — Feature-slice structure (do not flatten to component-based layout)
- #003 — TanStack Query for all server state (do not use useEffect + fetch)

---

Strategy 5: Skills as Living Workflows

Skills degrade when the project changes but the skill is not updated.

Skill Maintenance Checklist

Run this when making significant changes to the project:

• [ ] Do any skill commands reference renamed/moved files? Update paths.
• [ ] Do any skill commands reference deprecated tools or packages? Update.
• [ ] Have new conventions been adopted that conflict with existing skills?
• [ ] Are any skills never triggered? Consider merging into AGENTS.md or deleting.
• [ ] Are any AGENTS.md sections complex enough to deserve their own skill?

Skill Version Pinning

When a skill is created at a specific project checkpoint, note it:

---
name: add-api-endpoint
metadata:
  version: 2.0.0
  updated: 2026-02-18
  note: Updated for v2 route structure after API refactor
---

---

Strategy 6: Meta-Skills for Automated Improvement

The Skill-Creator Pattern

A "meta-skill" is a skill that writes other skills. After successfully completing a complex workflow, invoke the skill-creator meta-skill (or prompt the agent directly) to codify the workflow.

Trigger:

We just successfully [completed task]. This workflow is repeatable.
Create a new skill in .claude/skills/[name]/ that captures this workflow
so it can be triggered automatically next time.

The agent should: 1. Identify the steps performed 2. Extract the trigger phrases (what prompted the original task) 3. Write a SKILL.md with imperative instructions 4. Include exact commands, file paths, and validation steps 5. Run python scripts/package_skill.py .claude/skills/[name] to validate

Reflexion Loops

For complex tasks, build in a self-critique step:

Before finalizing this implementation:
1. Review what you just produced against the constraints in AGENTS.md
2. Identify any violations of the project conventions
3. Fix them, then confirm the implementation is compliant

This prevents the agent from bypassing AGENTS.md rules during long edits.

---

Strategy 7: Observability — Detecting When Agents Go Off-Track

Signs that agent configuration needs attention:

Minimal Observability Setup

Track agent errors in a lightweight log alongside ADRs:

docs/
└── agent-learnings/
    ├── 2026-01-15-wrong-import-paths.md
    ├── 2026-01-22-missing-migration-step.md
    └── TEMPLATE.md

Template:

# Agent Learning: [Date]

## Mistake Observed
[What the agent did wrong]

## Root Cause
[Which instruction was missing or incorrect]

## Fix Applied
[What was updated in AGENTS.md / skill]

## Verification
[How we confirmed the fix works]

---

Emerging Approaches (Experimental)

SAGE (Skill Augmented GRPO for Self-Evolution)

A reinforcement-learning framework where agents generate and refine skills across sequential tasks. Skills produced in earlier tasks are preserved in a library and reused in later tasks. Achieves ~8.9% improvement in goal completion with 59% fewer tokens. Not yet production-ready for typical codebases — relevant for teams building fine-tuned agents.

SEAgent (Self-Evolving Agent)

Enables autonomous skill discovery for unseen software via a World State Model and Curriculum Generator. Trains a specialist-to-generalist approach from software documentation. Significantly outperforms static-prompt baselines on OSWorld benchmarks.

Agentic Context Engineering

Agents acting as "context engineers" — rewriting and pruning their own context files to mitigate brevity bias and context collapse. Uses start_focus / complete_focus checkpoints where intermediate reasoning is compressed into a persistent "knowledge block," reducing token usage by 20%+ without accuracy loss.

For practical projects today, the human-curated approaches in Strategies 1–6 above remain more reliable and easier to audit.