| name | dev-context-engineering |
| description | Context-driven AI development with Claude Code and Codex. Use when transitioning teams to AGENTS.md workflows or multi-repo AI setups. Use when this capability is needed. |
| metadata | {"author":"echohaoran"} |
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.
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)
ln -s AGENTS.md CLAUDE.md
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.
Source: echohaoran/AI-AGENT-Skills — distributed by TomeVault.
