v1.0.0 · MIT · open source

Map before you modify.

An open-source agent skill that turns your codebase into a fine-grained modular wiki — so AI knows exactly which code to change for any given feature, and never spills into unrelated code.

Get started View on GitHub
Works with Claude Code, Codex, Cursor, Copilot, Gemini CLI
The problem

A codebase you don't know. A codebase too sprawling to hold in your head.

You inherit a 200k-line project. You ask an AI to add one feature. It does — but the next deploy breaks something you never asked it to touch. Sound familiar?

A client hands you 200,000 lines of code you've never read.
You ask an AI to make a small change in one module.
The AI silently edits a shared utility you didn't know existed.
Three modules break. No one notices until staging. Or worse — until production.
The fix

Map first. Then modify — only inside the lines.

map-then-modify is a protocol your AI follows. It produces a complete architectural map of your codebase, then enforces precise boundaries every time it changes code.

step 01 · map

Build a map of the whole codebase.

A recursive analysis produces an .architecture/ wiki — stable module IDs, precise file and line boundaries, interaction edges, risks, and confidence ratings on every claim.

step 02 · plan

Declare boundaries before touching code.

Every change starts with a written dev plan. The AI lists which files and lines it will edit — and which it explicitly will not. No silent surprises.

step 03 · modify

Edits stay strictly inside the plan.

If reality diverges from the map mid-edit, the wiki self-heals first, the plan expands transparently, and the change continues — without ever breaking what isn't documented.

No more silent regressions in modules nobody told the AI to change.
The map keeps up with the code on every successful change.
Risks, gotchas, and dead code surface early — never quietly.
You stay in the loop — the AI tells you what it healed and why.
Install

One command. Any agent platform.

Clone the repo into your agent's skills directory. Restart your agent. That's it.

# pick the skills directory for your agent (see table below)
git clone git@github.com:Luis-yl/map-then-modify.git \
    ~/.claude/skills/map-then-modify

Don't use Claude Code? Replace ~/.claude/skills/ with whichever skills directory your agent uses.

Platform
Skills directory
Claude Code
~/.claude/skills/
Codex CLI
~/.codex/skills/
Cursor / VS Code with Copilot
.cursor/skills/ or .copilot/skills/
Gemini CLI
~/.gemini/skills/
OpenCode / Cline / others
follow each platform's skills-loader convention

Once installed, just tell your agent: "map this project" — or any wording like "啃下这个项目", "safe refactor in an unfamiliar repo". The skill auto-triggers.

Usage

Three steps to go from zero to safe AI refactors.

Install once. Map once per project. Then keep telling your AI what to build — it stays inside the lines.

Install the skill

Clone the repo into your agent's skills directory and restart the agent. Full per-platform paths in the install section above.

What happens
  • The skill appears in your agent's available-skills list — no API key, no extra setup.

Map the codebase (once per project)

Open your agent at the project root. Then say something like this and let it run:

Say to your agent 啃下这个项目 map this codebase 分析这个仓库的架构
What happens
  • The skill auto-triggers MAPPING mode and runs anywhere from ~30 min (small repo) to a few hours (100k+ LOC).
  • Output lands at <repo>/.architecture/ — module docs, interaction maps, risks, coverage. Commit it to git.
  • When it finishes, the agent gives you a short summary: how many modules, top risks, what's next.

Ask for changes, every time

After mapping is done, you can ask your AI for any code change. The skill auto-detects the wiki exists and switches into DEVELOPMENT mode. No special incantation needed.

Say to your agent 给登录接口加 brute-force 防护 把 admin 后台改成只允许 IP 白名单 add a /health endpoint that reports DB latency
What happens
  • The agent writes a dev plan first under .architecture/dev-plans/ — listing the files and lines it will edit, AND which nearby code it explicitly will not touch.
  • Edits stay inside the plan. If reality diverges, the wiki self-heals first and the plan expands transparently.
  • When done, the agent syncs the wiki, runs the tests, and reports back — including any new risks it discovered.

Stop guessing. Start mapping.

It's free, open-source, and works with the agent you already use.

View on GitHub How to install