Claude Code Projects: what it actually changes

By Lazar Milicevic · Published September 21, 2026 · 10 min read

You've been building an app with Claude Code for three weeks. Every session, you re-paste the same context: the schema, the auth flow you rejected last Tuesday, the reason you picked Postgres over SQLite, the deployment target. You've got a CLAUDE.md that's grown to 400 lines because every fact you don't pin gets forgotten. Then Anthropic drops Claude Code Projects, and the pitch is: stop doing that.

Here's what it is, what it isn't, and how to wire it into a real workflow without breaking the parts of Claude Code that already work.

What Claude Code Projects actually is

Claude Code Projects is a persistent workspace inside the Claude Code harness that keeps conversation history, files, and delegated work tied to a single long-running dev effort. Instead of each session starting with an empty short-term memory (patched with CLAUDE.md and file re-reads), a Project holds an "always-on" thread that Claude Code returns to, plus a place to hand off longer tasks that continue while you're doing something else.

Three things matter about that framing:

1. The unit is the project, not the session. You're no longer bribing context back with markdown files at the top of every run.
2. Delegation is first-class. Long-running dev work — a migration, a scaffold, a refactor across 40 files — can be handed off and picked up later.
3. It sits on top of the existing Claude Code stack. MCP servers, subagents, hooks, permissions, and slash commands still work. This is not a rewrite; it's a memory + task layer.

If you already run Claude Code with a CLAUDE.md, some subagents, and a handful of MCP servers, Projects slots in above that.

Why "always-on" is a real change, not a UX repaint

The single biggest failure mode in agentic dev tools is context decay. You solve a problem on Monday. On Thursday the same agent proposes the same broken approach because it forgot why you rejected it. You waste 20 minutes explaining, or worse, you don't notice and merge the regression.

The classic workarounds:

• CLAUDE.md at repo root. Works, but it's a static ledger. You have to remember to update it, and it bloats.
• RAG over past chats. Fine in theory. In practice, the retriever misses the exact turn where you decided not to use Redis, and you get Redis proposed again.
• Long single sessions. Hits context limits, expensive, and if the session dies you lose everything.

Projects reframes this: the conversation is the memory. Decisions made yesterday stay accessible tomorrow without a re-paste ritual. You still want a CLAUDE.md for architectural invariants — those are stable rules Claude should never rediscover — but the day-to-day "why we did X" lives in the project thread itself.

The honest limit: persistent memory only helps if the model can actually retrieve the relevant slice. Expect the first few weeks to include cases where you have to nudge it ("remember we decided against SQS on Sept 4, use SNS+Lambda"). Treat the Project like an onboarding hire with a good notebook, not an omniscient partner.

The concrete workflow shift

Here's what a real dev loop looks like before and after Projects for a solo founder building a SaaS backend.

The delegation piece is what changes velocity most. A 40-minute test-suite migration doesn't need you in the driver's seat — it needs you to check results. Same for scaffolding a new service, writing migrations, or generating a first pass of API clients from an OpenAPI spec.

Setting up a project that won't rot

The failure mode I see most often with any persistent-memory tool is that it becomes a landfill. Everything goes in, nothing is pruned, and six weeks later the agent is confused by contradictory decisions.

A minimal, defensible setup for a new project:

# In your repo root
mkdir -p .claude/{commands,agents,hooks}
touch CLAUDE.md .claude/settings.json

Then a lean CLAUDE.md — stable invariants only, not running notes:

# Project: OrderFlow API

## Stack
- Python 3.12, FastAPI, SQLAlchemy 2.x
- Postgres 16 (managed, RDS)
- Deployed via Docker to ECS Fargate

## Non-negotiables
- All DB writes go through the repository layer, never raw SQL in routes
- No new dependencies without checking license (MIT/Apache/BSD only)
- Tests required for every route; use pytest fixtures in tests/conftest.py
- Migrations via Alembic, one migration per PR

## Explicitly rejected
- Redis (Postgres LISTEN/NOTIFY is enough for our scale)
- GraphQL (REST + OpenAPI is the contract)
- Celery (arq or native async tasks preferred)

## Style
- Ruff for lint, Black for format, mypy strict on src/

Keep it under ~150 lines. Anything longer belongs in the project thread or in a real doc.

For settings.json, lock down what the agent can do without asking:

{
  "permissions": {
    "allow": [
      "Bash(pytest*)",
      "Bash(ruff*)",
      "Bash(alembic*)",
      "Read(src/**)",
      "Write(src/**)",
      "Write(tests/**)"
    ],
    "deny": [
      "Bash(rm -rf*)",
      "Bash(git push*)",
      "Write(.env*)",
      "Write(infra/**)"
    ]
  }
}

The point isn't paranoia — it's that a long-running delegated task should never be able to git push --force or overwrite production Terraform. Persistent agents need persistent guardrails.

Delegation patterns that actually pay off

Not every task is worth delegating. Some heuristics from running Claude Code on real client work:

Good delegation candidates:

• Boilerplate scaffolding (new service, new endpoint following an existing pattern)
• Test generation for existing well-typed code
• Migration writing when the schema change is described precisely
• Documentation from source (docstrings → markdown, OpenAPI → client)
• Mechanical refactors (rename, extract, restructure imports across N files)

Bad delegation candidates:

• Anything where the acceptance criteria are fuzzy
• Cross-cutting architectural changes ("make this event-driven")
• Debugging a flaky test — the tight feedback loop matters
• Anything touching auth, billing, or PII paths without a review gate

A useful pattern is the delegate-then-review subagent. Define it once:

---
name: refactor-runner
description: Executes a well-scoped refactor plan across the codebase. Runs tests after each meaningful change. Stops and asks if tests fail twice in a row.
tools: Read, Write, Edit, Bash
---

You are executing a refactor plan. Rules:

1. Work in small commits. One logical change per commit.
2. After each change, run `pytest -x --ff` on the affected module.
3. If tests fail, attempt one fix. If they fail again, STOP and summarize.
4. Never modify migrations, .env files, or infra/.
5. Report a diff summary every 5 files touched.
6. Do not proceed past the scope defined in the initial task.

Then delegate concrete work: "Run refactor-runner to move all datetime.utcnow() calls to datetime.now(timezone.utc) across src/. Skip anything in vendor/."

That's a delegatable task. It has a clear scope, a clear stop condition, and a testable definition of done.

Where MCP servers fit in a Projects world

MCP (Model Context Protocol) servers are how you give Claude Code access to real systems — your database, GitHub, Linear, Sentry, S3. Projects doesn't replace MCP; it makes MCP more useful because the connections and decisions about them persist.

A pragmatic MCP setup for a backend project:

{
  "mcpServers": {
    "postgres-readonly": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-postgres", "postgres://readonly@localhost/orderflow_dev"]
    },
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "${GITHUB_TOKEN}"
      }
    },
    "sentry": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-sentry"],
      "env": {
        "SENTRY_AUTH_TOKEN": "${SENTRY_TOKEN}"
      }
    }
  }
}

Two rules that stop this from going sideways:

1. Read-only by default. The Postgres server above connects as a readonly user. If Claude needs to write, it goes through Alembic migrations reviewed by you — not by executing DDL on the fly.
2. Scoped tokens. The GitHub PAT should have access to this repo only, not your entire org. Same for every credential. Persistent agents amplify the blast radius of a leaked token.

Check the current pricing pages for both Anthropic's plans and any managed MCP hosting you use — the token math changes as models and tiers evolve, and it's the kind of thing worth budgeting monthly rather than eyeballing.

Costs, limits, and the honest tradeoffs

A persistent, delegating agent isn't free. The tradeoffs to name out loud:

Token cost. Persistent memory means Claude has more to reason over each turn. On any long project the effective context window is doing more work, which typically means higher per-turn cost. Watch your usage for the first week and set a monthly budget alarm rather than discovering the bill on the 30th.

Drift. The more a Project remembers, the more it can remember incorrectly. Add a weekly ritual: skim the recent thread, correct any wrong assumption you see, and update CLAUDE.md when a decision graduates from "we're trying this" to "this is how we do it."

Lock-in. Your project state lives in Anthropic's system. Mitigate by keeping the ground truth in your repo — CLAUDE.md, agent definitions, hooks, MCP configs all committed. If you had to walk away tomorrow, someone else could pick up the repo and re-onboard a fresh model in an afternoon. Don't put anything in the project thread that isn't reproducible from the repo.

Delegation review debt. If you delegate five long tasks and don't review them promptly, you end up with a merge queue of unreviewed AI work. That's worse than not delegating. Cap in-flight delegated tasks at what you can review the same day.

A minimal audit hook for delegated work

One thing I always add for long-running agent work: a hook that logs what happened, so you can review it without scrolling the thread.

# .claude/hooks/post-tool-use.yaml
hooks:
  - matcher: "Bash|Write|Edit"
    command: |
      echo "$(date -u +%FT%TZ) | $CLAUDE_TOOL | $CLAUDE_TOOL_INPUT" \
        >> .claude/audit.log

Then a slash command that summarizes what was done:

# .claude/commands/what-happened.md
Read .claude/audit.log for the last 24 hours.
Group entries by file and by task.
Summarize:
- Files modified (with line counts if available)
- Commands run (and any that failed)
- Anything touched outside src/ or tests/
Flag anything that looks unusual.

Now /what-happened gives you a real diff of your agent's day, and you have grep-able evidence when something breaks. This costs about 20 minutes to set up and saves hours the first time you need to answer "wait, when did that change?"

How BizFlowAI approaches this

We already run Claude Code + MCP stacks for clients — usually a scoped set of servers (Postgres read-only, GitHub, their ticketing tool, sometimes Stripe or a warehouse) plus a small library of subagents and hooks tuned to the codebase. Projects fits cleanly on top: same guardrails, same audit logging, same repo-committed configs, plus persistent context so the agent stops re-learning the same architecture every Monday.

If you're building something with Claude Code and want the persistent-collaborator setup wired in without the two weeks of trial and error — the MCP scoping, the delegation subagents, the audit hooks, and a CLAUDE.md that stays lean — that's the kind of engagement we do. Book a discovery call on bizflowai.io and bring a real repo; we'll scope it in 30 minutes.

What to do this week

If you're already on Claude Code:

1. Pick one active project. Move its running notes out of scratch files and into a Project thread.
2. Prune your CLAUDE.md to stable invariants only. Aim for under 150 lines.
3. Lock down settings.json — explicit allow/deny for Bash, Write, and any sensitive paths.
4. Add the audit hook above. You'll want the log the first time a delegated task does something unexpected.
5. Pick one delegatable task — a mechanical refactor is ideal — and run it end to end. Measure how long the review took vs. doing it yourself.

If you're not on Claude Code yet, don't start with Projects. Start with a boring CLAUDE.md, one MCP server, and one subagent on a real repo. Projects makes a working setup better; it doesn't rescue a broken one.

The interesting shift here isn't that Claude remembers. It's that the unit of work moves from "session" to "initiative." That changes how you plan, how you scope tasks, and how much you trust the thing between reviews. Get the guardrails right first, and the rest follows.

Work with BizFlowAI

If you'd rather have this built for you, that's what we do: production AI automation for solo founders and small teams — agents, integrations, and document pipelines that actually ship.

Book a free discovery call — 30 minutes, we map the highest-ROI automation in your workflow. No pitch deck, just engineering.

More guides like this on the BizFlowAI blog.