MANY REPOS.

MANY REPOS. MANY PROJECT. ONE WORKFLOW: A Guide to navigate .md frameworks.

Using AI like claude for most of your projects and products? Here’s what I’ve come up with to use with application like visual studio, github, and claude. Here's a workflow that scales across multiple repos/Projects for me.

The key insight from current Anthropic docs: the GitHub integration lets you add repos to a Project's knowledge and click "Sync now" to refresh, and you can add multiple repos to a single project, but there is no automatic push from your repo to Project knowledge — you still have to trigger the sync. So, the strategy is to make the repo the canonical source and treat each Claude Project as a synced mirror. Claude

1. Make the repo the single source of truth

Put every piece of context that matters in the repo itself, such as .md files. Never edit context only in the Claude Project UI — anything that lives only there will drift and get lost. Standardize a structure across every repo so the pattern is identical:

CLAUDE.md works as a router rather than a dump. Keep it under short.

2. Map repos to Projects deliberately

You don't always need one repo per Project. Three patterns work well:

• One repo, one Project: a self-contained product. Sync just that repo.
• Multiple related repos, one Project: a product with frontend/backend/infra repos that you reason about together. Add all of them to the same Project.
• Multiple unrelated products, one "org standards" Project : for cross-cutting things like coding conventions, design system, security rules. Sync a single org-standards repo here.

Decide the mapping up front and document it (a PROJECTS.md at the org level is useful).

3. Handle shared knowledge without copy-paste

The trap with many repos is duplicating context (style guides, security rules, deployment patterns). Two options:

Standards repo + git submodule or subtree: keep org-standards as its own repo, pull it into each product repo under docs/standards/. One edit, many repos benefit on next pull.

Standards repo synced into every Project (simpler): just add the standards repo to every relevant Claude Project alongside the product repo. Each Project gets standards + product-specific context.

The second is lower friction; the first is better if you want the standards versioned alongside the product.

4. Update cadence

Treat docs as code:

• Every PR that changes behavior must update the relevant .md. Add a PR template checkbox. A failing CI check works too — Claude Code's GitHub Action can review whether docs were updated.
• After merging to main, click "Sync now" in the affected Claude Project(s). Make this part of the "definition of done."
• Once a month, run a doc audit. You can literally ask Claude Code in the repo: "Read the last 30 days of commits and tell me which .md files are now stale."

5. Automate the boring parts

A few specific moves that pay off:

• PR template with a "Docs updated?" checkbox referencing CLAUDE.md and docs/.
• GitHub Action on push to main that pings you (or posts to Slack) "remember to sync Project X." There's no API to trigger sync programmatically yet. I’ve see an open features request that shows this is still waiting to be implemented. So the best you can do is automate the reminder.
• A /sync-check slash command in Claude Code that compares the git log since the last sync date against the doc files and should tell you what's likely stale. You write it once as a .claude/commands/sync-check.md and reuse it everywhere.
• An ADR (Architecture Decision Record) pattern in docs/decisions/ so important changes leave a dated trail rather than overwriting prose.

6. One concrete weekly rhythm

What does this look like in practice?

PRs update docs as part of the work. Then end of the week, for each active product, you open the Claude Project, hit "Sync now," then start a new chat and ask Claude to summarize what changed in the docs that week, I’ve a firm believer if redundant checks in your frameworks and making sure your co-worker “Claude” is part of a sort of “sync up” or a “sanity check” that the sync actually pulled the latest and that the doc updates make sense.

The biggest thing that makes this fall apart is letting context accumulate in chat conversations rather than getting promoted back into the repo.

IMPORTANT: When Claude gives you a useful explanation of how something works in a chat, ask it to write that up as a markdown file you can commit. That's how the system stays alive instead of decaying.

TECHNICAL HOW TO:

Where each one lives in a repo:

• CLAUDE.md → repo root
• pull_request_template.md → .github/pull_request_template.md (GitHub picks it up automatically for new PRs)
• sync-check.md → .claude/commands/sync-check.md (then run /sync-check or /sync-check 14d inside Claude Code in that repo)

The {{PLACEHOLDERS}} in CLAUDE.md are the only fields you need to fill per repo — everything else is structural and reusable as-is. A nice shortcut for rolling these out across many repos: put all three in a org-repo-template repo on GitHub and mark it as a template repository. New products start from it and inherit the structure; existing repos can pull the files over with a one-time copy.

One more thing worth adding once you've used these for a week or two: an org-standards repo with a single STANDARDS.md that captures the conventions that should apply everywhere (security, logging, error handling, API design). Add that repo to every Claude Project alongside the product repo. That way when you update a standard once, every Project gets it on the next sync — no copy-paste across repos. I use a guideline for myself as an ‘enterprise’ but you can definitely create the one that works for you.

If you want me to send you three sample files, including sync-check.md, pull_request_template.md, and claude.md DM me.

• # /sync-check

Goal: identify documentation that has likely drifted from the code, so I can update it before syncing this repo into its Claude Project(s).

• Pull_request_template.md

Goal: Steps a reviewer can run locally or connected to a CI/Storybook/preview.

• Claude.md

Goal: create a file for claude to understand the md files available, related projects, your workflow for claude coordination, known open questions, DO NOT rules for claude, etc…