Skip to content

Plan: Enhance Repository for AI-Assisted Development

Overview

Lay the groundwork for agentic development piece by piece. Add configuration files, documentation, and tooling to improve AI assistant effectiveness when working with this codebase.

Phase Dependencies

Phase 1 (Foundation) ─────┬──► Phases 2-4 (can run in parallel)
                          │
                          ├──► Phase 5 (Skills) - independent
                          │
                          └──► Phase 6 (Agents) - independent

Phases 2-4 ───► Phase 7 (Polish) - needs component docs first

Phase 8 (Testing) - can run independently at any time

Phase 9 (Beads) - independent exploration

Parallelization opportunities:

  • Phases 2, 3, 4 can run concurrently
  • Phase 5 and 6 can run concurrently
  • Phase 8 can start anytime

Recommended order within phases:

  • apis and service_utils before service-specific docs (shared dependencies)
  • Core services before ecom/platform components

Checklist

Phase 1: Foundation

  • Agentic Development Vision Doc (docs/agentic-development.md) - created, needs content
  • Strategic vision for human-AI collaboration
  • Philosophy and goals
  • Available agents and when to use them
  • Best practices for prompting
  • Future roadmap for agentic capabilities
  • Cleanup: Remove integration_service reference from root CLAUDE.md (component doesn't exist)
  • Create: .claude/skills/ directory

Phase 2: Component CLAUDE.md Files (Core Services)

  • components/bff_console/CLAUDE.md - Main BFF, request routing to microservices
  • components/identity_service/CLAUDE.md - Auth backends (Cognito/GCP), JWT handling
  • components/users_accounts_service/CLAUDE.md - User/account management
  • components/indexes_service/CLAUDE.md - Index lifecycle, Firestore patterns, workflow triggers
  • components/cluster_service/CLAUDE.md - Cluster pooling, state machines, DDB tables
  • components/billing_service/CLAUDE.md - Stripe integration, pricing models
  • components/api_keys_service/CLAUDE.md - API key management

Phase 3: Component CLAUDE.md Files (Shared & Foundation)

  • components/apis/CLAUDE.md - Shared Pydantic models across all services
  • components/service_utils/CLAUDE.md - Shared utilities, base classes, common patterns
  • components/monolith/CLAUDE.md - Service composition, Docker packaging, run_aws/run_gcp
  • components/auth_lambda/CLAUDE.md - Authentication Lambda
  • components/controller/CLAUDE.md - Account, billing, indexes, integrations logic
  • components/gcp_utils/CLAUDE.md - GCP-specific utilities

Phase 4: Component CLAUDE.md Files (Ecom & Platform)

  • components/ecom_indexer/CLAUDE.md - Indexing pipeline, retry logic, DLQ handling
  • components/ecom_utils/CLAUDE.md - Shared ecom models, repositories, API patterns
  • components/ecom_settings_exporter/CLAUDE.md - DDB streams → Cloudflare KV
  • components/ecom_metrics_consumer/CLAUDE.md - CloudWatch metrics processing
  • components/ecom_monitoring_service/CLAUDE.md - Index verification, alarms
  • components/search_proxy/CLAUDE.md - Hono worker, platform detection, search routing (TS)
  • components/agentic_search/CLAUDE.md - GenAI integration, conversation context (TS)
  • components/feature_flags/CLAUDE.md - Feature flag infrastructure

Phase 5: Component CLAUDE.md Files (Admin & Shopify)

  • components/admin_worker/CLAUDE.md - React Router worker, caching proxy (TS)
  • components/admin_lambda/CLAUDE.md - FastAPI admin backend, WriteSyncError pattern
  • components/shopify/CLAUDE.md - Shopify integration overview
  • components/shopify/admin_server/CLAUDE.md - FastAPI + GraphQL, webhooks, sessions
  • components/console/CLAUDE.md - React frontend for control plane

Phase 6: Infrastructure CLAUDE.md Files

  • infra/aws/CLAUDE.md - AWS CDK infrastructure
  • infra/gcp/CLAUDE.md - GCP Pulumi infrastructure
  • infra/controller/CLAUDE.md - Controller infrastructure
  • infra/admin/CLAUDE.md - Admin infrastructure
  • infra/ecom/CLAUDE.md - Ecom platform infrastructure

Phase 7: Skills

  • Create .claude/skills/ directory
  • .claude/skills/test-component.md - Run Pants tests for a component
  • .claude/skills/pr-review.md - Fetch and review a GitHub PR
  • .claude/skills/deploy-preflight.md - Pre-deployment checklist
  • .claude/skills/component-overview.md - List all components with descriptions for orientation

Phase 8: Additional Agents

  • .claude/agents/dynamodb-expert.md - Schema design, GSI optimization, query patterns
  • Focus: Design-time schema reviews and runtime query optimization
  • Distinction from plan-verifier: Deep DDB expertise vs general plan review
  • .claude/agents/infra-reviewer.md - CDK/Pulumi review, IAM analysis, security groups

Phase 9: Polish

  • Enhance root CLAUDE.md:
  • Service dependency overview/diagram
  • DynamoDB tables summary (table names, key schemas, GSIs)
  • Common debugging workflows
  • Environment variables reference

Phase 10: Test Coverage for Verifiability

  • Shore up unit tests across all services
  • Ensure critical paths have comprehensive coverage
  • Add missing edge case and error handling tests
  • Strengthen integration tests
  • Service-to-service interactions
  • DynamoDB/external service mocking
  • E2E test infrastructure
  • Decision needed: Migrate from Selenium to Playwright, or run both?
  • Current state: ui_tests/ uses Selenium + Firefox + LambdaTest
  • If migrating: Create migration plan for existing Page Object pattern
  • Hook up agents to Playwright for general e2e testing
  • Enable agents to run and verify UI flows
  • Create reusable test fixtures for agentic verification

Phase 11: Explore Beads

  • Evaluate Beads for agentic development
  • Understand the beads paradigm and how it differs from current approach
  • Assess integration potential with existing agents/skills
  • Prototype if promising
  • Success criteria:
  • Complete documentation review
  • Build one prototype workflow
  • Compare developer experience vs current approach
  • Go/no-go decision documented

Component CLAUDE.md Template (Python/FastAPI)

# {Component Name}

## Purpose

[1-2 sentence description]

## Key Files

- `path/to/main.py` - [description]
- `path/to/service.py` - [description]

## API Endpoints

| Method | Path        | Description |
| ------ | ----------- | ----------- |
| GET    | /api/v1/... | ...         |

## Domain Concepts

- [Concept 1]: [explanation]
- [Concept 2]: [explanation]

## DynamoDB Tables

| Table | PK  | SK  | GSIs |
| ----- | --- | --- | ---- |
| ...   | ... | ... | ...  |

## Environment Variables

| Variable | Required | Description |
| -------- | -------- | ----------- |
| ...      | Yes/No   | ...         |

## Patterns & Conventions

- [Pattern description]

## Dependencies

- [Service/Table it depends on]

## Related Components

- [Components that depend on this one]

## Testing

- Run: `pants test //components/{name}::`
- [Key fixtures or mocks]

## Common Pitfalls

- [Gotcha 1]
- [Gotcha 2]

Component CLAUDE.md Template (TypeScript/Cloudflare Worker)

# {Component Name}

## Purpose

[1-2 sentence description]

## Key Files

- `src/index.ts` - Worker entrypoint
- `src/app.ts` - [description]

## API Endpoints

| Method | Path        | Description |
| ------ | ----------- | ----------- |
| GET    | /api/v1/... | ...         |

## Domain Concepts

- [Concept 1]: [explanation]

## Environment Bindings

| Binding | Type         | Description |
| ------- | ------------ | ----------- |
| ...     | KV/DO/Secret | ...         |

## Patterns & Conventions

- [Pattern description]

## Dependencies

- [RPC services, KV namespaces, etc.]

## Testing

- Run: `npm test` or `npm run test:watch`
- Framework: Vitest with Cloudflare Workers pool

## Deployment

- `npx wrangler deploy`
- [Environment-specific notes]

## Common Pitfalls

- [Gotcha 1]
- [Gotcha 2]

Files Summary

Create (~40 files):

  • docs/agentic-development.md - exists, needs content
  • 26 component CLAUDE.md files
  • 5 infra CLAUDE.md files
  • 4 skills
  • 2 agents

Modify:

  • CLAUDE.md (root) - enhance + remove integration_service reference

Execution Notes

  • Work through phases sequentially, but leverage parallelization where noted
  • Each phase can be done in one session
  • Component files leverage exploration data already gathered
  • Skills and agents are standalone and can be done in any order after Phase 1
  • TypeScript components use different template than Python components
  • Consolidate or reference existing README.md files where applicable