Improvement Proposals
This chapter presents actionable proposals derived from the Context Engineering analysis. Each proposal addresses specific challenges identified from cross-team feedback and provides concrete implementation guidance.
Purpose: Transform context engineering insights into implementable improvements that teams can adopt incrementally.
Proposal Framework
All proposals in this chapter follow a consistent structure:
Each proposal includes:
- Problem Statement - The specific issue identified from team feedback
- Proposed Solution - Architecture and approach to address the problem
- Implementation Roadmap - Phased rollout with concrete deliverables
- Success Metrics - Measurable outcomes to track effectiveness
- CLAUDE.md Integration - How to document the solution for AI consumption
Proposal Categories
Process Proposals
Establish ongoing practices for maintaining context quality.
| Proposal | Description | Status |
|---|---|---|
| AI-First Decision Making | Systematic framework for evaluating AI as primary executor at every decision point | Documented |
| AI-DLC Mob Elaboration | AI-augmented development life cycle with collaborative elaboration sessions | Documented |
| Continuous Context Cleanup | Framework for identifying, documenting, and migrating deprecated patterns | Documented |
| Spec Extraction | Reverse-engineer specifications from existing implementations as "existing-fact" context | Documented |
Infrastructure Proposals
Build foundational systems that improve AI code generation accuracy.
| Proposal | Description | Status |
|---|---|---|
| Design System | Unified design system architecture for cross-platform consistency | Documented |
| shadcn/ui Foundation | Adopt shadcn/ui as the base for Web design system implementation | Documented |
| Agent-Friendly Knowledge Base | Migrate from Confluence to Git-based Markdown for AI agent access | Documented |
| Global Requirement Store | Product-oriented centralized requirement repository for cross-platform consistency | Documented |
| Tech Radar & Roadmaps | Interactive tech radar visualization and roadmap management for technology governance | Documented |
| Internal Spec Platform | Centralized specification hosting with date-based versioning and multi-product support | Documented |
| Claude Skills Adoption | Encourage teams to create, share, and maintain Claude Code Skills for reusable AI workflows | Documented |
Standards Proposals
Define terminology and documentation patterns for AI comprehension.
| Proposal | Description | Status |
|---|---|---|
| Ubiquitous Language | Cross-team terminology standards and domain glossary | Documented |
| Multi-Product Spec Management | Hierarchical specification management for multi-product organizations | Documented |
| Frontmatter Spec Coordination | Standardized YAML frontmatter schema for coordinating markdown documents across spec systems | Documented |
| CLAUDE.md Standards | Templates and best practices for AI guidance files | Planned |
Proposal Summaries
AI-DLC Mob Elaboration
Problem: Traditional SDLC approaches fail to leverage AI at critical decision points. Sequential handoffs between PM, RD, UX, and Architect create knowledge silos and miss edge cases that surface late in development.
Solution: Introduce Mob Elaboration sessions where all stakeholders collaborate simultaneously with AI:
- PM, RD, UX, Architect, and AI participate together
- AI surfaces edge cases, checks consistency, generates documentation
- Complete spec produced in single session
- Real-time synthesis across perspectives
Key Insight: Requirements quality improves dramatically when diverse perspectives challenge assumptions simultaneously. AI adds a tireless participant that can instantly surface gaps and maintain comprehensive documentation.
Continuous Context Cleanup
Problem: Context pollution accumulates as codebases evolve. Legacy patterns, deprecated frameworks, and inconsistent naming confuse AI code generation.
Solution: A five-phase continuous cycle:
- Identify - Detect pollution through AI output review
- Document - Update CLAUDE.md with current standards
- Mark - Add deprecation markers to legacy code
- Migrate - Incrementally move to modern patterns
- Verify - Monitor AI accuracy and iterate
Key Insight: Context cleanup should be integrated into the development workflow as an ongoing practice.
Design System
Problem: Component duplication is one of the most common AI code generation failures. AI creates new UI components instead of reusing existing ones because components are scattered, undocumented, and inconsistently named.
Solution: Establish a unified design system with:
- Centralized component directory with searchable index
- Cross-platform component mapping (Web, iOS, Android)
- Design tokens for consistent styling
- AI-optimized documentation with hints and usage guidelines
Key Insight: AI cannot "discover" unorganized components. If they aren't in expected locations with clear documentation, they effectively don't exist to AI.
shadcn/ui Foundation
Problem: Traditional component libraries (Ant Design, Material UI) create challenges for AI:
- Black-box implementations AI cannot understand
- Limited customization requiring CSS override hacks
- Version upgrades that break learned patterns
Solution: Adopt shadcn/ui's "copy-and-own" model:
- Full code ownership - modify freely without upstream dependencies
- AI-accessible implementation - code lives in your project
- Custom registry - share domain components across projects
- MCP integration - AI-powered component discovery
Key Insight: shadcn/ui transforms UI development from dependency consumption to infrastructure ownership, enabling both human and AI developers to work with fully accessible code.
Agent-Friendly Knowledge Base
Problem: Traditional knowledge systems (Confluence, SharePoint, Google Docs) are designed for human browsing, not machine consumption:
- Proprietary formats AI cannot parse
- No Git integration for version correlation
- Rich text that breaks AI parsing
- Permission complexity blocking agent access
Solution: Migrate to Git-based Markdown knowledge system:
- Plain Markdown with structured frontmatter
- Version control as source of truth
- MCP resource provider for AI access
- Semantic search and relationship graphs
Key Insight: Knowledge systems designed for human browsing actively obstruct AI agents. Making knowledge machine-readable while remaining human-editable enables agent collaboration.
Global Requirement Store
Problem: Requirements fragmented across platform-specific documents lead to implementation divergence. Each team (Web, iOS, Android, Backend) interprets the same PRD differently, and AI agents only see their platform's interpretation, causing:
- Inconsistent feature implementations
- Missing edge cases on some platforms
- Conflicting API contracts
- Redundant specification work
Solution: Establish a centralized, product-oriented requirement repository that feeds into existing multi-level spec systems:
- Product-centric organization (requirements grouped by product, not platform)
- Single source of truth with platform-specific supplements
- API-first contracts defined alongside requirements
- AI-native format with structured frontmatter metadata
- Version correlation linking requirement changes to implementation PRs
- Integration with spec systems like OpenSpec (changes -> specs -> archive)
Key Insight: The Global Requirement Store operates at the "What" level - defining product requirements. It feeds into spec systems like OpenSpec that operate at the "How" level - tracking implementation proposals, current state, and history. This multi-level integration provides complete traceability from requirement through proposal to deployed spec.
Ubiquitous Language
Problem: Terminology fragmentation causes AI code generation failures. When different teams use different terms for the same concept (camera vs device vs channel), AI produces inconsistent code requiring manual correction.
Solution: Establish cross-team terminology standards:
- Domain glossary with canonical term definitions
- Legacy term mapping for migration guidance
- Platform-specific naming conventions
- Validation tooling for enforcement
Key Insight: AI agents learn from code patterns. If the same concept has multiple names across the codebase, AI will perpetuate that inconsistency. Ubiquitous language is foundational for reliable AI code generation.
Multi-Product, Multi-Level Spec Management
Problem: Current AI development frameworks assume single product, single team environments. Multi-product organizations face challenges where AI agents lack context about organizational standards, miss product-specific constraints, and cannot detect conflicting specs across product boundaries.
Solution: Establish a hierarchical specification management framework with five levels:
- Level 0: Organization principles (always applicable)
- Level 1: Product specs (product-specific constraints)
- Level 2: Feature specs (what to build)
- Level 3: Platform specs (how to build per platform)
- Level 4: Implementation specs (detailed design)
With cross-cutting concerns handled via shared domains, API standards, design systems, and security policies that span all products.
Key Insight: Specifications should cascade from organization-wide principles to product-specific implementations while maintaining traceability. Lower levels inherit from higher levels (not copy), and overrides require explicit documentation with justification. This enables AI agents to navigate the full context hierarchy when generating code.
Frontmatter-Based Spec Coordination
Problem: Markdown documentation across organizations lacks standardized metadata. Each team invents different frontmatter fields, relationships exist only in prose, and AI agents cannot build document graphs without parsing entire content.
Solution: Establish a standardized YAML frontmatter schema for all specification documents:
- Required identity fields (id, title, type, status, version, owner)
- Explicit relationship declarations (inherits, depends_on, related, cross_product_refs)
- Override tracking with justification requirements
- AI guidance fields for context prioritization
- JSON Schema validation in CI pipelines
Key Insight: Markdown frontmatter is the natural coordination layer for specification documents. When standardized, frontmatter becomes a queryable graph of relationships, enabling AI agents to traverse specifications, detect conflicts, and maintain consistency without proprietary tooling.
Tech Radar & Roadmaps
Problem: Technology decisions scattered across wikis, spreadsheets, and tribal knowledge lead to duplicated evaluation efforts, inconsistent adoption, and poor visibility into the organization's technical direction.
Solution: Build Tech Radar and Roadmap capabilities in the internal developer portal:
- Interactive radar visualization with Adopt/Trial/Assess/Hold rings
- Four quadrants: Languages & Frameworks, Tools, Platforms, Techniques
- Technology proposal and voting workflow
- Strategic roadmap management with timeline views
- Historical tracking to compare radar changes over time
Key Insight: A unified Tech Radar provides the single source of truth for "what technologies should we use" and eliminates duplicated technology evaluations across teams.
Internal Spec Platform
Problem: Organizations managing multiple products face fragmented specification access. Specs are scattered across repositories, have no versioning for audit trails, lack cross-product visibility, and force AI agents to re-fetch and re-parse every session.
Solution: Build a centralized specification platform with date-based versioning:
- URL structure:
https://spec.{company.domain}/{date}/{product-id}/{spec-type}/specs/{spec-id} - Multiple spec types:
func,ux,api,infra(follows OpenSpec structure) - Date versioning over semver (objective, audit-friendly, multi-product sync)
- Version aliases:
/latest,/head,/{date} - Respects OpenSpec's flat capability naming convention
- Git-based resolution (no storage duplication)
- MCP integration for AI agent access
Key Insight: Date-based versioning fits specification management better than semantic versioning. "Show me 2024-09-15" is objective and auditable, while "which version was live in Q3?" requires interpretation. Same date across products means same snapshot, eliminating version alignment pain.
Reverse-Engineering Spec Extraction
Problem: Legacy codebases lack structured context. AI agents re-explore the same code every session, wasting context windows. Institutional knowledge is locked in implementations without documentation.
Solution: Reverse-engineer specifications from existing code to create "existing-fact" context:
- Four-layer extraction methodology (Boundaries, Structure, Behaviors, Edge Cases)
- Existing-fact specs distinct from forward-looking requirements
- AI-assisted extraction with human validation
- Confidence levels indicating trustworthiness
- 10-20x context compression vs raw code
Key Insight: Specifications extracted from implementations serve as compressed, authoritative context. A well-written spec is 5-20x smaller than the code it describes, dramatically reducing context window usage while preserving essential knowledge.
Implementation Priority
Recommended Order
- Start with Continuous Context Cleanup - Establishes the ongoing process
- Add Design Tokens - Foundation for consistent styling
- Implement shadcn/ui - Modern component architecture
- Define Ubiquitous Language - Cross-team terminology alignment
Quick Reference
Which Proposal Addresses Which Problem?
| Problem | Proposal |
|---|---|
| Requirements incomplete, edge cases missed | AI-DLC Mob Elaboration |
| Knowledge silos between PM/RD/UX/Architect | AI-DLC Mob Elaboration |
| AI creates duplicate components | Design System |
| AI uses deprecated patterns | Continuous Context Cleanup |
| Component library upgrade breaks code | shadcn/ui Foundation |
| AI hardcodes color values | Design System |
| AI can't access Confluence specs | Agent-Friendly Knowledge Base |
| Requirements scattered in platform-specific docs | Global Requirement Store |
| Inconsistent feature implementations across platforms | Global Requirement Store |
| Inconsistent naming across teams | Ubiquitous Language |
| AI doesn't know project conventions | CLAUDE.md Standards (planned) |
| AI lacks org-level context | Multi-Product Spec Management |
| Specs don't cascade across products | Multi-Product Spec Management |
| No spec inheritance or override tracking | Multi-Product Spec Management |
| Inconsistent frontmatter across docs | Frontmatter Spec Coordination |
| AI cannot discover document relationships | Frontmatter Spec Coordination |
| No validation of document references | Frontmatter Spec Coordination |
| Legacy code has no documentation | Spec Extraction |
| AI re-explores same code every session | Spec Extraction |
| Context window wasted on raw code | Spec Extraction |
| Institutional knowledge locked in implementations | Spec Extraction |
| Specs scattered across repositories | Internal Spec Platform |
| No spec versioning for audits | Internal Spec Platform |
| AI re-fetches specs every session | Internal Spec Platform |
| Cross-product specs not discoverable | Internal Spec Platform |
Team-Specific Entry Points
| Team | Start With |
|---|---|
| All Teams | AI-DLC Mob Elaboration for new features, Continuous Context Cleanup for existing code |
| Web Frontend | shadcn/ui Foundation |
| Mobile (iOS/Android) | Design System - Cross-platform mapping |
| Backend | Continuous Context Cleanup - Pattern documentation |
Success Metrics
Track these metrics across all proposals:
| Metric | Target | How to Measure |
|---|---|---|
| AI first-time accuracy | >80% | Track prompts requiring re-generation |
| Component reuse rate | >90% | Audit AI-generated PRs for new vs existing components |
| Deprecated code ratio | <20% | grep -r "@deprecated" vs total files |
| Design token adoption | 100% | grep for hardcoded color/spacing values |
| Cross-platform consistency | High | Visual comparison audit |
References
- Claude Code Documentation - Official documentation for CLAUDE.md and AI guidance files
- Model Context Protocol (MCP) - Anthropic's protocol for AI-tool integration
- OpenSpec - Specification-driven development framework for AI-assisted workflows