Crewforth 3.2.0 新增 Crew Map，為新加入者繪製專案地圖

You just joined a new project. Nothing looks familiar. There are folders called core, common and shared, three package.json files, and a docker-compose.yml that mentions a queue nobody has told you about.

The usual move today is to ask an AI agent to explore the repository. That works, more or less. It is also slow, it costs tokens every time, and when it tells you "the billing service talks to Stripe", you cannot tell whether it read that or guessed it.

Crewforth 3.2.0 adds Crew Map, which answers four questions about a project:

• What each part does
• What it's built with
• Who talks to whom
• Where something is wrong

It does this without running anything. It reads the files.

What Crewforth is

Crewforth is an open-source (MIT) kit for Claude Code. It adds 14 specialist agents, 40 skills, 13 /crew-… commands, and hooks that enforce the rules that matter: a destructive command is refused, a commit waits for your approval, a leaked key never reaches history. Crew Map is one part of it.

npx crewforth init

Step 1: a scan that cites its sources

The first part is a scanner. It uses no model. It reads manifests and source for Node and TypeScript, Python, Go, .NET, Java and Kotlin, and writes one file, .crewforth/crew-map.json, with:

• the modules,
• the external resources they touch (databases, caches, queues, outside APIs),
• the endpoints each module provides and the ones it calls.

Every module, every line between modules and every finding carries the file:line it was read from. If the map says module A calls module B, you can open the exact line.

Two details matter in practice:

• It is deterministic. The same tree gives the same bytes. Run it with --check in CI and the build fails when the map is out of date.
• It does not copy secrets. A configuration value is read only to name its kind (a Postgres URL, a Redis host), not stored.

Step 2: the model describes, but only what was read

A list of modules is not yet understanding. So /crew-map runs the scanner and then asks the model to describe what it found:

• at most two sentences per module on what it is for,
• a short overview of the project,
• a layer for each module: ui, api, service, data, infra, tool or library,
• the domain it serves (billing, auth, search...),
• a tour of up to eight stops that a newcomer reads in order.

Each of these must cite lines the scan itself read. crew-map.sh --validate refuses a description that cites anything else or nothing, a layer not on the list, a domain written as a sentence, a tour stop that points at no module or visits one twice, and any scanner field changed by hand. When you scan again, descriptions that still hold are kept and the rest are dropped.

Module READMEs are read too. On a real project, four of ten modules had nothing else to describe them by.

This is the part I care about most: the model writes prose, but it cannot invent structure. A connection the model proposes is drawn differently from one a file proves.

Step 3: look at it in Studio

Studio is Crewforth's local panel (npx crewforth studio). Its Map view (press p) reads crew-map.json and scans nothing itself.

• Modules sit in their layers, from UI down to Infrastructure. Each card names the module, its domain, up to three things it is built with and the outside services it calls.
• Lines are solid where a file proves them, dotted where inferred, and marked where the model proposed them.
• Search dims everything it does not match.
• The tour steps through the map at the bottom of the pane.
• The inspector shows a module's entry point, its folders and their file counts. Any file:line can be copied, and a finding can be copied as a task for the crew.
• Compare with matches another project's calls against this one's endpoints, which helps when a frontend and a backend live in separate repos.

crew-planner, the agent that turns an unclear request into tasks, reads the map when it works on an unfamiliar project, so it starts from the same picture you do.

Where something is wrong

The scanner has ten gap rules. Five are proven by the lines they cite. The other five are conclusions from absence, such as an endpoint that nothing calls. Absence is easy to get wrong, so those five are hidden and only counted until their false-positive rate is measured. You can ask to see them.

Also in 3.2.0

• Watch your crew from your phone. Studio can make a read-only viewer link, shown as a QR code. A phone on the same Wi-Fi opens the panel without ssh or a tunnel. Transcripts are hidden unless you tick them, a link lasts eight hours, and you can revoke it.
• A new agent that writes your docs. crew-docs-agent owns READMEs, guides, release notes and store listings. Legal and privacy texts run on the critical tier and are audited by crew-privacy-agent.
• A guard that tells you what it stopped. When the shell gate stops git reset --hard, git clean -f, git push --force or rm -r, one line says what it would have discarded, overwritten or deleted.

The full list is in the CHANGELOG.

Limits

• Supported stacks are Node/TypeScript, Python, Go, .NET, Java and Kotlin. Others are not mapped yet.
• Connections come from what the files show: imports, project references, HTTP calls. Wiring decided at runtime is missed.
• The scan is free. The descriptions run in your Claude Code session and cost tokens like any other work.

Try it

npx crewforth init      # or: npx crewforth adopt, for an existing repo

Then, in Claude Code:

/crew-map

and open the Map with npx crewforth studio.

If it helps you find your way around a codebase, a star on GitHub is the simplest way to tell me, and it helps other people find the project. If the map gets your project wrong, please open an issue with what it missed. That is the feedback I need most.