Improve CLAUDE.md with richer project context

[bmbouter]

Problem

The current CLAUDE.md (169 lines) provides basic project structure and commands but is missing context that would make AI agents significantly more effective when working on this codebase.

Suggested Improvements

• Key architecture decisions — why certain patterns were chosen (e.g., domain-based org isolation, X-RH-IDENTITY flow, content guard design)
• Common pitfalls — things that trip up new contributors (e.g., migration ordering, test database setup, fixture requirements)
• Code conventions — naming patterns, serializer/viewset patterns used consistently across the codebase
• Testing guidance — how to run specific test subsets, what fixtures are available, how to set up test data
• Deployment context — how the three-service architecture (api/content/worker) affects development decisions
• Dependency relationships — how pulp-service relates to pulpcore, what's inherited vs. overridden
• Recent major changes — any in-progress migrations or deprecations that agents should be aware of

The agent should read the existing CLAUDE.md, explore the codebase thoroughly (especially docs/ARCHITECTURE.md), and produce an improved version that gives AI agents the context they need to make good decisions.

[alcove-bot]

🤖 SDLC Planning Committee Analysis

I've analyzed issue #1109 as the SDLC Planning Committee. Here's our comprehensive implementation plan:

Summary

Enhance CLAUDE.md by synthesizing architectural knowledge from docs/ARCHITECTURE.md, codebase analysis, and deployment patterns into actionable guidance. Focus on architectural decisions, common pitfalls, code patterns, testing workflows, and the unique multi-tenant authentication model to help AI agents make informed decisions when working on this Django plugin for Pulpcore.

Key Team Findings

System Architect: The current CLAUDE.md lacks crucial context about domain-based org isolation, the three-layer middleware stack (WSGI → Django → aiohttp), and how X-RH-IDENTITY flows through authentication backends. Need to document the plugin extension pattern where this service extends upstream Pulpcore with Red Hat-specific features.

Security (Red Team): Critical gap in documenting the multi-tenant security model - how org_id isolation works, certificate-based auth patterns, and the blast radius of domain-based permissions. Missing guidance on secure handling of X-RH-IDENTITY headers and common auth pitfalls.

QA/Testing Specialist: Missing crucial testing guidance - how to set up test data with X-RH-IDENTITY, available fixtures, domain isolation testing, and how to run specific test subsets effectively.

Work Breakdown

1. Analyze and synthesize architectural context (2-3h, Low risk)

   • Extract key architectural decisions from docs/ARCHITECTURE.md
   • Map plugin vs. upstream Pulpcore responsibilities

2. Document authentication and multi-tenancy patterns (2-3h, Medium risk)

   • Document X-RH-IDENTITY flow through middleware stack
   • Explain domain-based org isolation patterns

3. Extract code conventions and common patterns (1-2h, Low risk)

   • Identify naming conventions, model patterns, viewset structure
   • Document plugin extension patterns

4. Document testing workflows and fixtures (2h, Low risk)

   • Extract testing patterns from functional tests
   • Document domain isolation testing approaches

5. Identify common pitfalls and gotchas (2-3h, Medium risk)

   • Migration ordering issues, middleware stack gotchas
   • Three-service architecture deployment considerations

6. Synthesize enhanced CLAUDE.md (3-4h, Low risk)

   • Integrate all findings while preserving dev container section

Open Questions for Human Input

• Are there any ongoing schema migrations or deprecations AI agents should be aware of?
• Should we document the plugin upgrade process and compatibility matrix with upstream Pulpcore?
• Are there specific database query patterns or optimization techniques agents should follow?

This plan would significantly improve AI agent effectiveness by providing the missing architectural context and practical patterns needed for informed development decisions.