Context Engineering for AI-Augmented Development

Quick Reference

Task Primary Skill Reference

Write AGENTS.md / CLAUDE.md agents-project-memory memory-patterns.md

Create implementation plan dev-workflow-planning —

Write PRD / spec docs-ai-prd agentic-coding-best-practices.md

Create subagents agents-subagents —

Set up hooks agents-hooks —

Configure MCP servers agents-mcp —

Git workflow + worktrees dev-git-workflow ai-agent-worktrees.md

Orchestrate parallel agents agents-swarm-orchestration —

Application security software-security-appsec —

Assess repo maturity this skill maturity-model.md

Full idea-to-ship lifecycle this skill —

Multi-repo coordination this skill multi-repo-strategy.md

Regulated environment setup this skill regulated-environment-patterns.md

Fast-track onboarding this skill fast-track-guide.md

Context lifecycle (CDLC) this skill context-development-lifecycle.md

Convert existing repos this skill repo-conversion-playbook.md

Team transformation this skill team-transformation-patterns.md

Measure AI coding impact dev-ai-coding-metrics —

The Paradigm Shift

Software development is shifting from tool-centric workflows to context-driven development:

Dimension Traditional Context-Driven

Source of truth Jira + Confluence Repository (AGENTS.md + docs/)

Standards Wiki page .claude/rules/ (loaded every session)

Execution Human writes code Agent writes code with structured context

Knowledge transfer Onboarding meetings AGENTS.md = instant context

Planning Sprint board docs/plans/ with dependency graphs

Review Humans only Humans + AI disclosure checklist

Why it matters: Unstructured AI coding ("vibe coding") is 19% slower with 1.7x more issues (METR). Structured context engineering inverts this — agents become faster and more reliable than solo coding. But context quality matters more than quantity: ETH Zurich research (March 2026) shows LLM-generated context files degrade performance by 3% while human-written files help only when limited to non-inferable details.

Cross-platform convention: AGENTS.md is the primary file. CLAUDE.md is always a symlink (ln -s AGENTS.md CLAUDE.md ). Codex reads AGENTS.md directly; Claude Code reads the symlink. One file, two agents, zero drift.

See: references/paradigm-comparison.md for full mapping + migration playbook.

Complete Lifecycle: Idea to Ship

flowchart LR P1["1 CAPTURE\n─────────\nIdea → Spec\n(docs-ai-prd)"] P2["2 PLAN\n─────────\nSpec → Plan\n(dev-workflow-planning)"] P3["3 CONTEXT\n─────────\nPlan → Repo Context\n(agents-project-memory)"] P4["4 EXECUTE\n─────────\nContext → Code\n(agents-swarm-orchestration)"] P5["5 VERIFY\n─────────\nCode → Quality Gate\n(agents-hooks)"] P6["6 SHIP\n─────────\nVerified → Merged\n(dev-git-workflow)"] P7["7 LEARN\n─────────\nShipped → Better Context\n(CDLC)"]

P1 --> P2 --> P3 --> P4 --> P5 --> P6 --> P7
P7 -.->|"feedback\nloop"| P1

style P1 fill:#e8daef,color:#4a235a
style P2 fill:#d6eaf8,color:#1b4f72
style P3 fill:#d5f5e3,color:#1e8449
style P4 fill:#fdebd0,color:#7e5109
style P5 fill:#fadbd8,color:#922b21
style P6 fill:#d4efdf,color:#1e8449
style P7 fill:#fef9e7,color:#7d6608

Seven phases from idea capture to learning. Each phase references the primary skill and key actions.

Phase 1: CAPTURE — Idea to Spec

Skill: docs-ai-prd

• Capture the idea in docs/specs/feature-name.md

• Use docs-ai-prd to generate a structured PRD

• Include: problem statement, success criteria, constraints, non-goals

• Architecture extraction: docs-ai-prd/references/architecture-extraction.md

• Convention mining: docs-ai-prd/references/convention-mining.md

Phase 2: PLAN — Spec to Implementation Plan

Skill: dev-workflow-planning

• Create docs/plans/feature-name.md from the spec

• Break into tasks with dependencies and verification steps

• Identify parallelizable tasks for multi-agent execution

• Estimate token budget for the implementation

Phase 3: CONTEXT SETUP — Plan to Repository Context

Skills: agents-project-memory, agents-subagents

• Update AGENTS.md if the feature introduces new patterns

• Add/update .claude/rules/ for any new conventions

• Create specialized subagents if needed (e.g., test-writer, migration-helper)

• For multi-repo: ensure coordination repo is updated if shared context changes

Phase 4: EXECUTE — Context to Working Code

Skills: agents-swarm-orchestration, dev-git-workflow

• Create feature branch and worktree for isolation

• Execute plan tasks — use subagents for parallel work

• Follow plan verification steps after each task

• Use --add-dir for cross-repo context if needed

Phase 5: VERIFY — Code to Quality + Compliance Gate

Skills: agents-hooks, dev-git-workflow

• Run automated verification: tests, lint, type-check

• Run compliance gates (if regulated): signed commits, secrets scan, SAST, PII check

• AI disclosure: complete PR template with AI involvement

• Human review: code reviewer verifies AI-generated code

Phase 6: SHIP — Verified to Merged + Deployed

Skill: dev-git-workflow

• PR approved by reviewer (different person from author)

• Security review for critical paths (auth/, payments/, crypto/)

• Merge to main via merge commit (not squash — audit trail)

• Deployment approved by DevOps (separate from code approval)

Phase 7: LEARN — Shipped to Better Context

Framework: CDLC (context-development-lifecycle.md)

• Session retrospective: what context was missing or misleading?

• Update AGENTS.md and rules based on learnings

• Extract patterns: if you repeated the same instruction 3+ times, make it a rule

• Track metrics: agent success rate, rework rate, token cost

SDLC Compression

Traditional regulated SDLC: Requirements (14d) → Dev (3w) → QA (6-8w) → Deploy (1-2w) = 12-16 weeks.

The 2-month QA is a late discovery problem, not a QA problem. CDLC shifts verification left into every phase:

Phase Traditional With CDLC Key Enabler

Requirements 14 days 3-5 days AI-assisted specs, architecture extraction

Development 3 weeks 2-3 weeks Structured context = fewer mistakes

QA 6-8 weeks 1-2 weeks Automated gates + verification per task

Deployment 1-2 weeks 1-3 days Pre-verified compliance, audit trail

Total 12-16 weeks 4-6 weeks 60-65% compression

QA compresses the most because convention violations, integration bugs, compliance gaps, and missing tests are caught during development — not discovered weeks later. Automated compliance gates mean QA focuses on what humans are good at: exploratory testing and edge cases.

See: references/context-development-lifecycle.md § SDLC Compression for full analysis with caveats.

Repository Maturity Quick Assessment

Level Per-Repo Org-Wide (100 repos) Key Action

L0 No Context No AGENTS.md No shared standards Create AGENTS.md (30 min)

L1 Basic AGENTS.md <50 lines Template repo exists, 10% adoption Add rules + docs (2-4 hrs)

L2 Structured

• rules + docs/specs Shared rules, 50% adoption Add agents + hooks (1-2 days)

L3 Automated

• agents + hooks + CI gates Compliance gates, 80% adoption Start CDLC (2-4 weeks)

L4 Full CE

• CDLC active + metrics InnerSource governance, 95%+ Sustain + optimize

Quick self-assessment: 14 yes/no questions in references/maturity-model.md.

Multi-Repo at Scale

For organizations with many repositories, use a coordination layer pattern:

Coordination Repo (recommended for polyrepo)

flowchart TD CR["Coordination Repo\n━━━━━━━━━━━━━━\nOrg AGENTS.md\nShared rules\nSync scripts"]

R1["Service A\n─────────\nLocal AGENTS.md\nLocal rules"]
R2["Service B\n─────────\nLocal AGENTS.md\nLocal rules"]
R3["Service C\n─────────\nLocal AGENTS.md\nLocal rules"]
RN["... 97 more"]

CR -->|"mandatory rules\n(CI/CD sync)"| R1
CR -->|"mandatory rules\n(CI/CD sync)"| R2
CR -->|"mandatory rules\n(CI/CD sync)"| R3
CR -.->|sync| RN

DEV["Developer Session\nclaude --add-dir coordination-repo"]
DEV -->|"reads shared"| CR
DEV -->|"reads local"| R2

style CR fill:#d6eaf8,color:#1b4f72
style DEV fill:#d5f5e3,color:#1e8449
style R1 fill:#fef9e7,color:#7d6608
style R2 fill:#fef9e7,color:#7d6608
style R3 fill:#fef9e7,color:#7d6608
style RN fill:#f5f5f5,color:#666666

One meta-repo holds shared context: org-wide AGENTS.md, mandatory rules, shared skills, sync scripts. Individual repos maintain focused local context.

Load shared context into any repo session

claude --add-dir ../coordination-repo

Shared vs Local Context

Category Scope Distribution

Mandatory (compliance, security, data handling) All repos CI/CD sync (automated)

Recommended (coding standards, commit conventions) Most repos Template sync or --add-dir

Local (architecture, domain patterns, subagents) Per-repo Maintained by repo team

Symlink Convention (enforced everywhere)

Every repo, every time

ln -s AGENTS.md CLAUDE.md

CI validates: [ -L CLAUDE.md ] or fail

See: references/multi-repo-strategy.md for full patterns, sync scripts, token budgets, and InnerSource governance.

Regulated Environments

For FCA-regulated EMIs and similar organizations:

Mandatory Compliance Rules

Install these in every repo (copy from assets/ directory):

Asset File Install To Purpose

compliance-fca-emi.md

.claude/rules/compliance-fca-emi.md

Audit trail, separation of duties, SM&CR

data-handling-gdpr-pci.md

.claude/rules/data-handling-gdpr-pci.md

Safe/prohibited data categories

ai-agent-governance.md

.claude/rules/ai-agent-governance.md

Approved tools, disclosure, training

pr-template-ai-disclosure.md

.github/pull_request_template.md

AI involvement checklist per PR

fca-compliance-gate.yml

.github/workflows/fca-compliance-gate.yml

Signed commits, secrets, SAST, PII, AI disclosure

Core Regulatory Principles

• Audit trail: Signed commits, merge commits, immutable history (PS21/3)

• Separation of duties: AI cannot approve/merge/deploy; different reviewer required

• No sensitive data in context: PII, card data, credentials never in agent prompts or files

• AI disclosure: Every PR declares AI involvement and human verification

• Accountability: Named Senior Manager accountable for AI governance (SM&CR)

• Portability: Dual-agent strategy (Claude Code + Codex) avoids vendor lock-in (PS24/16)

• Agent isolation: Sandbox execution for automated agent runs (microVM/gVisor for CI/CD)

• Platform audit: GitHub Agent HQ audit logs with actor_is_agent identifiers (Feb 2026)

Also track: NIST AI Agent Standards Initiative (Feb 2026) — US framework for agent identity, security, governance. FINRA 2026 — first financial regulator to require AI agent action logging and human-in-the-loop oversight.

See: references/regulated-environment-patterns.md for full regulatory mapping and incident response.

Agent and Tool Selection

Primary Agents (use both)

Both Claude Code and Codex are available as first-class agents on GitHub Agent HQ (Feb 2026), with enterprise audit logging (actor_is_agent identifiers), MCP allowlists, and organization-wide policy management.

Capability Claude Code Codex

Best for Interactive planning, complex refactoring Async batch tasks, issue triage

Context file Reads CLAUDE.md (symlink) Reads AGENTS.md (direct)

Execution Local, interactive Cloud, sandboxed

GitHub Agent HQ Yes (cloud sessions) Yes (cloud sessions)

Subagents Yes (.claude/agents/ ) No

Hooks Yes (.claude/hooks/ ) No

MCP servers Yes No

Worktrees Yes Branches

Multi-repo --add-dir

Single repo per task

Decision Tree

flowchart TD Q1{"Interactive task?\n(needs back-and-forth)"} Q2{"Batch of independent\ntasks?"} Q3{"Complex refactor\nneeding subagents?"} CC1["Claude Code"] CX1["Codex\n(parallel async)"] CC2["Claude Code"] EITHER["Either works\n(prefer Claude Code\nfor regulated envs)"]

Q1 -->|Yes| CC1
Q1 -->|No| Q2
Q2 -->|Yes| CX1
Q2 -->|No| Q3
Q3 -->|Yes| CC2
Q3 -->|No| EITHER

style CC1 fill:#d5f5e3,color:#1e8449
style CC2 fill:#d5f5e3,color:#1e8449
style CX1 fill:#d6eaf8,color:#1b4f72
style EITHER fill:#fef9e7,color:#7d6608

Supplementary Tools

Tool Use When Context File

Cursor IDE-embedded editing, quick fixes .cursor/rules

GitHub Copilot Inline suggestions during manual coding —

Context as Infrastructure

Six principles for treating context like production infrastructure:

• Version it — AGENTS.md and rules live in git, reviewed in PRs

• Review it — Context changes get the same review rigor as code changes

• Test it — Run a task with new context to verify it works before committing

• Scope it — One concern per rule file; clear sections in AGENTS.md

• Budget it — Monitor token cost; compress or split when context grows

• Retire it — Remove stale rules quarterly; outdated context is worse than no context

Anti-Patterns

Anti-Pattern Problem Fix

Vibe coding No spec, no plan, just "build it" Start with Phase 1 (CAPTURE)

Context bloat 2000-line AGENTS.md nobody reads Split into rules/ and references; keep AGENTS.md <200 lines

Over-specification Rules for every edge case Write rules for patterns, not exceptions

Tool accumulation 5 AI tools, no coordination Pick 2 primary (Claude Code + Codex), standardize context

Parallel Jira+context Maintaining specs in both Jira and repo Jira for portfolio; repo for execution context

Static context Write AGENTS.md once, never update CDLC: monthly review, retire stale rules

God agent One agent does everything Specialized subagents for distinct tasks

Skipping verification Trust AI output without review Phase 5 (VERIFY) is mandatory, not optional

Compliance bypass "We'll add gates later" Install mandatory rules from day 1 (assets/)

Separate CLAUDE.md CLAUDE.md and AGENTS.md with different content Always symlink: ln -s AGENTS.md CLAUDE.md

LLM-generated context Auto-generated AGENTS.md duplicates discoverable info (-3% perf) Write only non-inferable details (ETH Zurich 2026)

Single-file at scale One massive file can't scale beyond modest codebases Three-tier architecture: hot memory → agents → cold knowledge

Do / Avoid

Do:

• Start with maturity assessment before investing in automation

• Use the lifecycle (7 phases) — skipping CAPTURE and PLAN is the #1 cause of rework

• Install compliance rules before development starts (not after)

• Run context retrospectives — context without feedback loops decays

• Use both Claude Code and Codex for their respective strengths

Avoid:

• Don't migrate from Jira overnight — use the incremental playbook

• Don't create 500-line AGENTS.md files — use progressive disclosure

• Don't skip the symlink convention — drift between AGENTS.md and CLAUDE.md causes bugs

• Don't let context go stale — if it hasn't been updated in 90 days, it's suspect

• Don't treat AI-generated code differently from human code in review rigor

Navigation

References

File Content Lines

paradigm-comparison.md Old vs new paradigm mapping, 2026 industry validation ~200

maturity-model.md 5-level maturity, adoption data, research caveats ~280

fast-track-guide.md 30-min, 2-hour, batch tracks + quality research insight ~250

context-development-lifecycle.md CDLC + three-tier architecture, Manus patterns, ETH research ~615

multi-repo-strategy.md Coordination patterns, GitHub Agent HQ, VS Code CE ~420

regulated-environment-patterns.md FCA/EMI, NIST, FINRA 2026, sandbox isolation, GH audit ~400

repo-conversion-playbook.md Step-by-step conversion with real scripts and templates ~790

team-transformation-patterns.md AI-native vs traditional teams, shadow experiments, risk assessment ~230

Assets (Copy-Ready Templates)

File Install To Purpose

compliance-fca-emi.md .claude/rules/

FCA/EMI audit trail and separation of duties

data-handling-gdpr-pci.md .claude/rules/

GDPR/PCI safe and prohibited data categories

ai-agent-governance.md .claude/rules/

AI tool restrictions and disclosure

pr-template-ai-disclosure.md .github/

PR template with AI involvement checklist

fca-compliance-gate.yml .github/workflows/

CI/CD compliance gates

Related Skills

Skill Relationship

agents-project-memory How to write AGENTS.md (L1 foundation)

dev-workflow-planning Creating implementation plans (Phase 2)

docs-ai-prd Writing specs for AI agents (Phase 1)

agents-subagents Creating specialized subagents (Phase 3)

agents-hooks Event-driven automation (Phase 5)

agents-mcp MCP server configuration

dev-git-workflow Git patterns, worktrees (Phase 4-6)

agents-swarm-orchestration Parallel agent execution (Phase 4)

Web Verification

83 curated sources in data/sources.json across 10 categories:

Category Sources Key Items

Context Engineering 10 Anthropic CE, Fowler, CDLC, Codified Context (arxiv), Manus lessons

AGENTS.md Standard 6 agents.md spec, Linux Foundation, ETH Zurich evaluation (arxiv)

Paradigm Shift 8 OpenAI Harness, METR study, Anthropic 2026 Trends Report

Tool Documentation 10 Claude Code, Codex, GitHub Agent HQ, VS Code CE guide

Multi-Repo Patterns 6 Spine Pattern, InnerSource, Git submodules, GH Actions

Security Tooling 10 Gitleaks, Semgrep, NIST Agent Standards, sandbox patterns

FCA/EMI Compliance 9 PS21/3, SS1/23, SM&CR, PS24/16, FINRA 2026 AI agents

Data Protection 4 IAPP GDPR, PCI SSC, Anthropic DPA, OpenAI DPA

SDLC and DevOps 6 DORA metrics, GitHub Enterprise AI Controls, branch protection

Practitioner Insights 14 Stripe Minions, Block/Dorsey, HBR AI layoffs, Harvard/P&G, OpenAI guide

Verify current facts before final answers. Priority areas:

• AGENTS.md specification changes (agents.md — 60,000+ repos, evolving rapidly)

• Claude Code and Codex feature updates (now on GitHub Agent HQ)

• GitHub Enterprise AI Controls evolution (MCP allowlists, agent governance)

• FCA regulatory updates (PS21/3, SS1/23, PS24/16 — watch for consultations)

• NIST AI Agent Standards Initiative (comments due April 2026)

• FINRA AI agent guidance evolution (annual oversight reports)

• CDLC framework evolution (community-driven, externally validated March 2026)

• Context file effectiveness research (ETH Zurich, Codified Context — ongoing)

Fact-Checking

• Use web search/web fetch to verify current external facts, versions, pricing, deadlines, regulations, or platform behavior before final answers.

• Prefer primary sources; report source links and dates for volatile information.

• If web access is unavailable, state the limitation and mark guidance as unverified.