-
Notifications
You must be signed in to change notification settings - Fork 37
Description
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:
- Token leak bugs (fixed 2024-11-15) - need
token-handling.mdpattern - Access control bugs (Enhance project access control in backend handlers #268, fix: enhance copySecretToNamespace to handle existing controller ref… #299) - need
rbac-enforcement.mdpattern - PVC cleanup issues (Bug: [Brief description] PVCs aren't cleaned up #375, Bug: [restarted timed-out sessions fail to start due to multi-attach PVC error] #298) - need
resource-lifecycle.mdpattern - Git operation errors (Bug: [Session should not fail if Context Repo cloning fails & other Git Operation Issues] #376) - need
git-operations.mdpattern
Proposed Solution
Build a comprehensive lifecycle system with:
- Enforcement: Manual review NOW, but architecture ready to flip to automated enforcement later
- Ownership: Hybrid - Tech leads + automated drift detection
- Coverage: Prioritize critical security patterns first (address real bugs), then add incrementally
- 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.mdpatterns/drafts/andpatterns/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:
-
token-handling.md(CRITICAL)- Token extraction, redaction in logs, storage in secrets
- Addresses: Token leak bugs (fixed 2024-11-15)
- Detection: Automated
-
rbac-enforcement.md(CRITICAL)- SelfSubjectAccessReview pattern, namespace isolation
- Addresses: Access control bugs Enhance project access control in backend handlers #268, fix: enhance copySecretToNamespace to handle existing controller ref… #299
- Detection: Partial
-
resource-lifecycle.md(CRITICAL)- OwnerReferences, PVC cleanup, Job monitoring
- Addresses: PVC issues Bug: [Brief description] PVCs aren't cleaned up #375, Bug: [restarted timed-out sessions fail to start due to multi-attach PVC error] #298
- Detection: Automated
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-reviewlabels)
Phase 5: High Priority Patterns (Weeks 9-12)
Create 3 additional patterns:
secret-management.md- Secrets in K8s Secrets, rotationstatus-update-patterns.md- CR /status subresource patterngit-operations.md- Git clone, fork, PR creation (addresses Bug: [Session should not fail if Context Repo cloning fails & other Git Operation Issues] #376)
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.mdwebsocket-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:
- GitHub issue with
pattern-proposallabel - PR with draft in
patterns/drafts/ - Approval: 2 tech leads OR 1 Distinguished Engineer
- Run drift detection, document violations
- Move to
patterns/root, update INDEX.md - 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
- Review plan with Distinguished Engineer and tech leads
- Assign ownership roles (Security, Backend, Frontend, Operator leads)
- Approve priority tier 1 patterns
- Allocate resources for Phase 1-2 (4 weeks)
- Begin Phase 1 implementation
Related PRs/Issues
- PR feat: implement memory system for better Claude Code context #359: Memory system implementation (introduced patterns)
- PR feat: add memory system and repomix analysis for Claude Code #360: Repomix analysis (memory system foundation)
- Bugs Enhance project access control in backend handlers #268, fix: enhance copySecretToNamespace to handle existing controller ref… #299: RBAC issues
- Bugs Bug: [Brief description] PVCs aren't cleaned up #375, Bug: [restarted timed-out sessions fail to start due to multi-attach PVC error] #298: PVC cleanup issues
- Bug Bug: [Session should not fail if Context Repo cloning fails & other Git Operation Issues] #376: Git operation errors