Skip to content

Pattern Lifecycle Management System #411

@jeremyeder

Description

@jeremyeder

Summary

Establish a comprehensive lifecycle management system for .claude/patterns/ to maintain, validate, and evolve code patterns across the codebase.

Problem Statement

The .claude/patterns/ directory was created in PR #359 but lacks a lifecycle management system:

  • No update process - 20+ commits to backend/operator since pattern creation, potential drift
  • No ownership model - Unclear who maintains which patterns
  • No validation - No checks that code follows documented patterns
  • Missing critical patterns - Gaps in coverage (token handling, RBAC, resource lifecycle)
  • No drift detection - Can't detect when code diverges from patterns

Recent issues indicating pattern needs:

Proposed Solution

Build a comprehensive lifecycle system with:

  1. Enforcement: Manual review NOW, but architecture ready to flip to automated enforcement later
  2. Ownership: Hybrid - Tech leads + automated drift detection
  3. Coverage: Prioritize critical security patterns first (address real bugs), then add incrementally
  4. Integration: Bidirectional links between patterns ↔ ADRs ↔ context files

Implementation Plan

Phase 1: Foundation (Weeks 1-2)

Create directory structure and core documentation:

  • patterns/INDEX.md - Searchable catalog (domain, criticality, scenario)
  • patterns/README.md, patterns/CONTRIBUTING.md, patterns/template.md
  • patterns/drafts/ and patterns/archive/ directories
  • Add frontmatter to 3 existing patterns (owner, criticality, related ADRs)
  • Cross-reference ADRs and context files (bidirectional links)
  • Update CODEOWNERS for pattern ownership

Phase 2: Critical Security Patterns (Weeks 3-4)

Create 3 new critical patterns addressing real bugs:

  1. token-handling.md (CRITICAL)

    • Token extraction, redaction in logs, storage in secrets
    • Addresses: Token leak bugs (fixed 2024-11-15)
    • Detection: Automated
  2. rbac-enforcement.md (CRITICAL)

  3. resource-lifecycle.md (CRITICAL)

Phase 3: Drift Detection Infrastructure (Weeks 5-6)

Build automation tooling:

  • scripts/detect-pattern-drift.sh - Pattern drift detection script
  • .claude/pattern-detection.yml - Detection rules configuration
  • Test locally, generate baseline drift report

Phase 4: CI Integration (Weeks 7-8)

Integrate with GitHub Actions:

  • .github/workflows/pattern-drift.yml - CI pattern checking (informational, NOT blocking)
  • Update PR template with pattern conformance checklist
  • Integrate with Amber automation (amber:pattern-fix, amber:pattern-review labels)

Phase 5: High Priority Patterns (Weeks 9-12)

Create 3 additional patterns:

Phase 6: Enforcement Readiness (Weeks 13-16)

Prepare for future automation (DISABLED):

  • .claude/linter-config.yml - Enforcement toggle (off by default)
  • Document 4-stage rollout strategy (informational → warn → block critical → full)
  • Exception process documentation

Phase 7: Ongoing Expansion

Backlog patterns (add as needed):

  • shadcn-component-usage.md, pvc-lifecycle.md, form-validation.md
  • websocket-patterns.md, operator-reconciliation.md, test-patterns.md, logging-patterns.md

Ownership Matrix

Pattern Primary Owner Criticality Detection
k8s-client-usage.md Security Lead CRITICAL Automated
token-handling.md Security Lead CRITICAL Automated
rbac-enforcement.md Security Lead CRITICAL Partial
error-handling.md Backend Lead HIGH Automated
resource-lifecycle.md Operator Lead HIGH Automated
react-query-usage.md Frontend Lead HIGH Automated

Owner Responsibilities:

  • Review pattern updates
  • Triage drift detection issues (weekly)
  • Validate pattern currency (monthly)
  • Mentor developers on pattern usage
  • Approve exceptions

Pattern Lifecycle Workflow

States: PROPOSED → DRAFT → ACTIVE → DEPRECATED → ARCHIVED

Creation Process:

  1. GitHub issue with pattern-proposal label
  2. PR with draft in patterns/drafts/
  3. Approval: 2 tech leads OR 1 Distinguished Engineer
  4. Run drift detection, document violations
  5. Move to patterns/ root, update INDEX.md
  6. Announce to team

Update Process:

  • Triggered by ADR changes, refactoring, bug fixes
  • PR updating pattern file
  • Run drift detection
  • Approval: 1 pattern owner OR 1 tech lead

Validation (Manual for Now):

  • Monthly pattern health checks
  • PR review integration (template checklist)
  • Label violations: pattern-drift

Integration with Memory System

Bidirectional Links:

  • ADRs → Patterns: "Implementation Patterns: [link]"
  • Patterns → ADRs: "This pattern implements ADR-0002"
  • Context Files → Patterns: "Core Patterns: [link]"
  • Pattern frontmatter references related files

Pattern Index Searchable By:

  • Domain (Security, Backend, Frontend, Data)
  • Criticality (Critical, High, Medium, Low)
  • Scenario ("I'm adding an endpoint")
  • Tags (#security, #kubernetes)
  • Detection Status (Automated, Partial, Manual)

Success Metrics

Short-term (3 months):

  • 6+ active patterns
  • 100% ADRs/context files link to patterns
  • Drift detection running weekly
  • 0 critical violations in new PRs

Medium-term (6 months):

  • 10+ active patterns
  • 80%+ automated detection
  • 20% faster PR reviews

Long-term (12 months):

  • Automated enforcement enabled
  • Amber auto-fixes pattern violations

Files to Create (20+)

Pattern Infrastructure:

  • .claude/patterns/{INDEX,README,CONTRIBUTING,template}.md
  • .claude/patterns/{drafts,archive}/.gitkeep

New Critical Patterns:

  • .claude/patterns/{token-handling,rbac-enforcement,resource-lifecycle}.md

Automation:

  • scripts/detect-pattern-drift.sh
  • .claude/pattern-detection.yml
  • .claude/linter-config.yml
  • .github/workflows/pattern-drift.yml

Files to Modify (13+)

Add Pattern Links:

  • CLAUDE.md, 3 context files, 5 ADR files

Add Frontmatter:

  • 3 existing pattern files

Update for Integration:

  • .github/{CODEOWNERS,pull_request_template.md}
  • .github/workflows/amber-auto-review.yml

Implementation Guide

Complete cold-start prompt available at:
.claude/prompts/pattern-lifecycle-coldstart.md

This file contains the full implementation plan that any Claude Code session can use to implement the system without needing prior context.

Next Actions

  1. Review plan with Distinguished Engineer and tech leads
  2. Assign ownership roles (Security, Backend, Frontend, Operator leads)
  3. Approve priority tier 1 patterns
  4. Allocate resources for Phase 1-2 (4 weeks)
  5. Begin Phase 1 implementation

Related PRs/Issues

Metadata

Metadata

Assignees

No one assigned

    Labels

    documentationImprovements or additions to documentationenhancementNew feature or request

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions