dev-context-engineering（开发环境工程）

Context Engineering for AI-Augmented Development

Quick Reference

The Paradigm Shift

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

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

1. Capture the idea in docs/specs/feature-name.md
2. Use docs-ai-prd to generate a structured PRD
3. Include: problem statement, success criteria, constraints, non-goals
4. Architecture extraction: docs-ai-prd/references/architecture-extraction.md
5. Convention mining: docs-ai-prd/references/convention-mining.md

Phase 2: PLAN — Spec to Implementation Plan

Skill: dev-workflow-planning

1. Create docs/plans/feature-name.md from the spec
2. Break into tasks with dependencies and verification steps
3. Identify parallelizable tasks for multi-agent execution
4. Estimate token budget for the implementation

Phase 3: CONTEXT SETUP — Plan to Repository Context

Skills: agents-project-memory, agents-subagents

1. Update AGENTS.md if the feature introduces new patterns
2. Add/update .claude/rules/ for any new conventions
3. Create specialized subagents if needed (e.g., test-writer, migration-helper)
4. 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

1. Create feature branch and worktree for isolation
2. Execute plan tasks — use subagents for parallel work
3. Follow plan verification steps after each task
4. Use --add-dir for cross-repo context if needed

Phase 5: VERIFY — Code to Quality + Compliance Gate

Skills: agents-hooks, dev-git-workflow

1. Run automated verification: tests, lint, type-check
2. Run compliance gates (if regulated): signed commits, secrets scan, SAST, PII check
3. AI disclosure: complete PR template with AI involvement
4. Human review: code reviewer verifies AI-generated code

Phase 6: SHIP — Verified to Merged + Deployed

Skill: dev-git-workflow

1. PR approved by reviewer (different person from author)
2. Security review for critical paths (auth/, payments/, crypto/)
3. Merge to main via merge commit (not squash — audit trail)
4. Deployment approved by DevOps (separate from code approval)

Phase 7: LEARN — Shipped to Better Context

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

1. Session retrospective: what context was missing or misleading?
2. Update AGENTS.md and rules based on learnings
3. Extract patterns: if you repeated the same instruction 3+ times, make it a rule
4. 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:

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

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

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):

Core Regulatory Principles

1. Audit trail: Signed commits, merge commits, immutable history (PS21/3)
2. Separation of duties: AI cannot approve/merge/deploy; different reviewer required
3. No sensitive data in context: PII, card data, credentials never in agent prompts or files
4. AI disclosure: Every PR declares AI involvement and human verification
5. Accountability: Named Senior Manager accountable for AI governance (SM&CR)
6. Portability: Dual-agent strategy (Claude Code + Codex) avoids vendor lock-in (PS24/16)
7. Agent isolation: Sandbox execution for automated agent runs (microVM/gVisor for CI/CD)
8. 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.

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

Context as Infrastructure

Six principles for treating context like production infrastructure:

1. Version it — AGENTS.md and rules live in git, reviewed in PRs
2. Review it — Context changes get the same review rigor as code changes
3. Test it — Run a task with new context to verify it works before committing
4. Scope it — One concern per rule file; clear sections in AGENTS.md
5. Budget it — Monitor token cost; compress or split when context grows
6. Retire it — Remove stale rules quarterly; outdated context is worse than no context

Anti-Patterns

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

Assets (Copy-Ready Templates)

Related Skills

Web Verification

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

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.