Skip to content

multi-repo-workflow.md

Latest commit

 

History

History
90 lines (59 loc) · 2.61 KB

multi-repo-workflow.md

File metadata and controls

90 lines (59 loc) · 2.61 KB
Raw

Multi-Repository Operations

The Reality

Proportione operates 20+ repositories across two GitHub accounts (personal and organization). These span:

  • Client projects (always private)
  • Internal tools and automation
  • WordPress sites and content
  • Sales, marketing, and CRM documentation
  • Research and publications

Each repository has its own CLAUDE.md. Each one is a self-contained operating brief.

The Challenge

Context fragmentation. A single client engagement might touch:

  • The CRM repo (deal and contact management)
  • The WordPress repo (landing page or case study)
  • The automation repo (email campaigns, data pipelines)
  • The sales repo (proposal documentation, prospecting playbook)

Without a system, Claude Code would start each session blind.

Our Approach

1. One CLAUDE.md Per Repository

Every repository has a CLAUDE.md at its root. This is non-negotiable. Even repositories with a single script get a brief CLAUDE.md explaining what it does and how it connects to the broader system.

2. Cross-References Between Repos

Each CLAUDE.md includes a section mapping related files in other repositories:

## Cross-references
- Brand manual: `Wordpress/win2win/docs/brand/BRAND-MANUAL.md`
- CRM architecture: `automation-brain/proportione/docs/arquitectura-servicios.md`
- Backlog: `automation-brain/proportione/docs/backlog-crm-soporte-*.md`

This means Claude Code, working in any repo, knows where to find related context.

3. Origin Tracking

When a file is copied or derived from another repository, we document its origin:

## File origins
| File in this repo | Copied from |
|---|---|
| `crm/guia-crm.md` | `automation-brain/proportione/docs/guia-crm.md` |

This prevents drift and establishes the source of truth.

4. Consistent Structure

All CLAUDE.md files follow the same sections:

  1. Scope
  2. Structure
  3. Cross-references
  4. Tools and services
  5. Deployment patterns (where applicable)

Consistency means Claude Code can navigate any repository in the system with the same mental model.

The Result

When we open a new Claude Code session in any repository, the AI arrives with:

  • Full understanding of that project's scope
  • Knowledge of where related work lives
  • Deployment patterns ready to execute
  • Awareness of constraints and conventions

There is no "onboarding" delay. Every session starts at full operational capacity.

Principle

Managing multiple repositories with AI is not about the AI. It is about the discipline of documentation. CLAUDE.md files are the connective tissue that turns a collection of repos into an operating system.