Claude Code existing codebase map: edit से पहले 45 मिनट का safe workflow

जब आप Claude Code को किसी existing codebase में इस्तेमाल करते हैं, तो पहला output code diff नहीं होना चाहिए। पहला output एक map होना चाहिए। repo map बताता है कि app कहां से start होती है, कौन से folders important हैं, आज किन areas को नहीं छूना है, change verify कैसे होगा, और अगले person को क्या handoff देना है। बिना map के छोटी request भी broad cleanup, unrelated refactor या hard-to-review changes में बदल सकती है।

यह guide beginners के लिए 45-minute workflow देती है ताकि edit करने से पहले repository को समझा जा सके। Official Claude Code overview बताता है कि Claude Code codebase read कर सकता है, files edit कर सकता है और commands run कर सकता है। इसी power की वजह से boundaries पहले define करनी चाहिए।

Related reading के लिए existing codebase first prompts, Claude Code permissions guide और CLAUDE.md starter template देखें।

45-minute repo map

पहले 25 minutes read-only discovery, 10 minutes map writing, 5 minutes first safe task चुनने और 5 minutes plan review में लगाएं। Perfect architecture document मत बनाइए। Goal है एक working map जिससे छोटा, reversible और verifiable change किया जा सके।

flowchart TD
  A["Read-only inventory"] --> B["Entry points find करें"]
  B --> C["Safe और risky areas अलग करें"]
  C --> D["एक first patch चुनें"]
  D --> E["Proof commands fix करें"]
  E --> F["repo-map.md लिखें"]

Entry point वह जगह है जहां app शुरू होती है: route, API handler, server bootstrap, CLI command, scheduled job या content loader। Risky area वह जगह है जहां छोटी गलती trust या revenue को प्रभावित कर सकती है: authentication, billing, deletion, production config, secrets, deploy scripts, analytics और ad tags।

Step 1: read-only inventory लें

पहले ऐसे commands चलाएं जो repository को describe करते हैं पर modify नहीं करते। Windows PowerShell में यह block first pass के लिए काफी है।

git status --short
Get-ChildItem -Force | Select-Object Name, Mode, Length
Get-ChildItem -Recurse -File -Include package.json,astro.config.*,next.config.*,vite.config.*,README*,CLAUDE.md,AGENTS.md | Select-Object -ExpandProperty FullName
rg --files | Select-Object -First 120

Stack, docs, generated folders, cache directories और uncommitted changes देखें। अगर working tree dirty है, तो पहले समझें changes आपके हैं या किसी और के। इससे AI accidentally दूसरे काम को overwrite नहीं करता।

Claude Code को पहला prompt read-only boundary के साथ दें।

Read this repository as an existing codebase. Do not edit files yet.

Goal:
- Create a first repo map in 45 minutes
- Pick exactly one safe starter task
- Identify areas that should not be touched today

Return:
1. Up to 8 important directories
2. Up to 5 runtime or content entry points
3. Risky areas with reasons
4. Three safe starter task candidates
5. Candidate proof commands

If something is uncertain, write "unverified" instead of guessing.

Do not edit files yet session को exploration mode में रखता है जब तक reviewable plan तैयार नहीं होता।

Step 2: repo-map.md लिखें

Discovery को सिर्फ chat में मत छोड़िए। एक छोटा repo-map.md लिखिए जिसे next session reuse कर सके। Official memory docs बताते हैं कि CLAUDE.md persistent project instructions रख सकता है, लेकिन first-pass research अलग file में रखना बेहतर रहता है। Stable rules बाद में CLAUDE.md में move करें।

# repo-map.md

## Purpose
- First working map for using Claude Code safely in this repository

## Entry points
| Type | File | Role | Proof |
| --- | --- | --- | --- |
| Web | site/src/pages/index.astro | Home page | npm run build |
| Content | site/src/content/blog | Article source | Open article URL |

## Safe candidates
- docs/
- site/src/content/blog/
- Small display copy

## Do not touch today
- .env and secrets
- Auth, billing, deletion flows
- Deploy scripts
- Generated dist and cache folders

## First safe task
- Improve one article CTA
- Change one file only
- Verify with build and preview

## Remaining risks
- Production data flow is unverified
- External service integrations need a separate pass

यह complete architecture नहीं है। यह first useful change से पहले guardrail है।

Step 3: permissions से boundary मजबूत करें

Instructions helpful हैं, लेकिन enforcement नहीं हैं। Official permissions docs allow, ask और deny rules explain करते हैं। Existing repo की first session में reads और safe checks allow करें, build या edit पर ask करें, और push, destructive commands तथा secrets deny करें।

{
  "permissions": {
    "allow": [
      "Bash(git status *)",
      "Bash(git diff *)",
      "Bash(rg *)",
      "Bash(npm run test *)",
      "Read"
    ],
    "ask": [
      "Bash(npm run build *)",
      "Edit(site/src/content/blog/**)"
    ],
    "deny": [
      "Bash(git push *)",
      "Bash(rm -rf *)",
      "Read(.env)",
      "Read(**/.env)",
      "Edit(scripts/deploy*)"
    ]
  }
}

यह JSON starting point है। आपके project में npm run test न हो सकता है, और editable path अलग हो सकता है। Main habit यह है कि allow बढ़ाने से पहले deny decide करें।

Step 4: पहला safe patch चुनें

Map बनने के बाद task छोटा, reversible और easy to verify होना चाहिए। तीन practical use cases अच्छे हैं।

पहला है content CTA fix। जैसे popular article को naturally products और training से connect करना। Usually एक content file change होती है और build plus preview से verify हो जाती है।

दूसरा है README या CLAUDE.md में proof commands add करना। Known build, test, lint और preview commands लिखने से future sessions में search कम होती है और app behavior नहीं बदलता।

तीसरा है one-screen copy या date format change। Patch को one or two files तक रखें और test, screenshot या local preview से validate करें। Auth, billing, permissions और deletion को first patch से बाहर रखें।

Using repo-map.md, implement only the first safe task.

Target:
- site/src/content/blog/example.mdx

Requirements:
- Make the final CTA more natural
- Keep internal links to /products/ and /training/
- Do not change pubDate, category, tags, author, or heroImage
- Change this one file only

After finishing, report:
1. Changed files
2. Why they changed
3. Proof commands run
4. Remaining risks

यह prompt broad request को reviewable patch में बदल देता है।

Step 5: map को भी check करें

Repo map prose है, लेकिन minimum sections check हो सकते हैं। इसे check-repo-map.js के रूप में save करें।

const fs = require("node:fs");

const file = process.argv[2] || "repo-map.md";
const text = fs.readFileSync(file, "utf8");
const required = ["Entry points", "Safe candidates", "Do not touch today", "First safe task", "Remaining risks"];
const missing = required.filter((heading) => !text.includes(heading));

if (missing.length > 0) {
  console.error(`Missing repo-map sections: ${missing.join(", ")}`);
  process.exit(1);
}

console.log(`OK: ${file} has the minimum repo-map sections.`);

node check-repo-map.js repo-map.md

Script simple है, लेकिन हर session को same handoff format छोड़ने के लिए मजबूर करता है।

Common failures

Failure one है बहुत broad request से start करना: “refactor the app” या “improve quality”। Fix है read-only discovery, maximum file count, do-not-touch areas और proof commands पहले define करना।

Failure two है generated artifacts को map में mix करना। dist, .astro, .next, coverage, node_modules repo को बड़ा दिखाते हैं पर first understanding में मदद नहीं करते। जब तक वे deployment target न हों, exclude करें।

Failure three है external services को हल्का समझना। Email, payment webhooks, ads, analytics और CRM code में छोटे हो सकते हैं पर business impact बड़ा होता है। पहले read करें, edit अलग task में करें।

Failure four है build के बाद रुक जाना। Build pass हो सकता है, फिर भी mobile layout, code blocks, CTAs या internal links broken हो सकते हैं। Content site में preview खोलकर body, code blocks, /products/ और /training/ check करें।

Review checklist

Lens	Check	Bad sign
Diff	Only requested files changed	Large incidental formatting
Entry	You know how change is loaded	Edited file is never used
Risk	Auth, billing, delete, prod untouched	Secrets or deploy changed
Proof	Command or manual check exists	Only “probably fine”
Funnel	CTA and internal links fit	Product links feel forced
Handoff	Remaining risks written	Next session repeats discovery

Checklist Claude Code पर अविश्वास के लिए नहीं है। यह work repeatable बनाती है।

Revenue paths भी map करें

ClaudeCodeLab जैसे content site में code map में monetization paths भी होने चाहिए। कौन से articles search traffic लाते हैं? Reader कहां download, product या consultation देखता है? Ready templates के लिए product library देखें। Team rollout, permissions और content operations के लिए Claude Code training देखें।

जब revenue paths map में होते हैं, तो छोटा CTA patch सिर्फ copy edit नहीं रहता। आप internal links, product pages, forms, analytics और ads भी check करते हैं। Code correct होने से revenue नहीं आता, reader को next step भी clear चाहिए।

Summary

Claude Code के साथ first 45 minutes code rewrite में नहीं, codebase mapping में लगाएं। Repo inventory करें, entry points identify करें, risks mark करें, एक safe task चुनें, proof commands fix करें और repo-map.md छोड़ें। उसके बाद one or two files का छोटा patch करें।