Claude Code-тағы Git worktree: параллель сессиялар

Ailoot-пен жұмыс істеу туралы практикалық ақпарат құжаттамада берілген.

Claude Code-тағы git worktree дегеніміз не#

Бір қалтада бірнеше агентті қатар іске қосу — 2026 жылғы қарқынмен vibe-coding жасағанда кездесетін негізгі қиындық. ЖИ агенттері кодты адамның кімнің неге тиіп жатқанын бақылап үлгеруінен жылдам жазады. Файлдар оқшауланбаған болса, бір каталогта екі Claude Code сессиясын қатар іске қосу бір сессияның екіншісінің жұмысын үстінен жазуымен аяқталады.

Git worktree бұл мәселені файлдық жүйе деңгейінде шешеді. Сіз жұмыс істейтін негізгі бір каталог болады. claude --worktree feature-auth пәрмені бөлек тармақта .claude/worktrees/feature-auth/ қалтасын жасап, Claude Code-ты сол жерде іске қосады. Файлдар оқшауланған. Өзгерістерді әдейі біріктірмейінше, бір сессия екіншісінде көрінбейді.

Anthropic-тің ресми құжаттамасында былай делінген:

Өзіңізді тексеруге арналған ишара: егер commit ішінен файлдардың жартысы басқа біреудің жұмысы болып шыққан кез болса, сізге worktree керек.

git worktree кәдімгі тармақтан несімен ерекшеленеді#

Стандартты Git жұмыс барысы: сіз main тармағындасыз да, git checkout feature-x пәрменін іске қосасыз — Git жұмыс көшірмесіндегі файлдарды үстінен жазып шығады. Іске қосулы npm run dev процесі бұзылады, себебі package.json өзгеріп кеткен. Commit жасалмаған өзгерістеріңізді stash-ке сақтап, IDE қайта индекстеуін күтесіз. Кері ауысқанда бәрі қайтадан үстінен жазылып, өзгерістерді тағы да stash-ке салып, pop жасауға тура келеді.

Git worktree басқа жол ұсынады: тармақтар арасында бір қалтаны ауыстырудың орнына, басқа тармаққа арналған екінші қалта жасайсыз. git worktree add ../project-feature-x feature-x пәрмені feature-x тармағындағы файлдары бар ../project-feature-x/ каталогын жасайды. main бастапқы қалтада қалады, ал әзірлеу сервері жұмысын жалғастырады.

Бұрын Claude Code-тағы worktree режимін қолмен баптау керек еді: git worktree add, одан кейін cd, содан соң claude — әрі мұны әр терминалда қайталау қажет болатын. --worktree жалаушасы (-w деп те жазылады) осы үшеуін бір пәрменмен орындайды.

Бірінші параллель сессияны іске қосу: --worktree жалаушасы#

Ең қарапайым мысал. Бірінші терминалды жобаның түбірлік каталогында ашыңыз:

claude --worktree feature-auth

Claude Code үш әрекет орындайды:

1. origin/HEAD күйінің көшірмесі бар .claude/worktrees/feature-auth/ қалтасын жасайды (әдетте бұл — әдепкі тармағыңыз).
2. worktree-feature-auth деген жаңа тармақ жасайды.
3. Сессияны осы қалтада іске қосады.

Бір репозиторийдің түбірлік каталогында екінші терминал ашыңыз:

claude --worktree bugfix-123

Дайын. Дискідегі файлдары мен Git тармақтары әртүрлі екі Claude Code сессиясы. Біріншісінде аутентификация кодын жазып, екіншісінде өтпей қалған тестіні түзетсеңіз, олар физикалық тұрғыдан бір-біріне кедергі келтіре алмайды.

Атау тергіңіз келмесе, Claude өзі ойлап табады:

claude --worktree
# → .claude/worktrees/bright-running-fox/ сияқты бір нәрсе жасайды

Git-ті жаңадан үйреніп жүргендерге кеңес: .claude/worktrees/ жолын .gitignore ішіне қосыңыз. Әйтпесе, негізгі қалтада git status іске қосылғанда, барлық worktree мазмұны бақыланбайтын файлдар ретінде көрінеді:

# .gitignore
.claude/worktrees/

Алдын ала ескеретін жайт: жаңа каталогта --worktree пәрменін алғаш рет іске қоспас бұрын, оған жалаушасыз кәдімгі claude пәрменімен кіріп, жұмыс кеңістігіне сенім диалогында келісіңіз. Олай етпесеңіз, жалауша “trust not accepted” қатесімен істемейді, оған headless режиміндегі -p жалаушасын қосқанның өзінде.

Worktree-лер қайда орналасады және оларды қалай табуға болады#

Әдепкі орналасуы бекітілген: репозиторий түбіріндегі .claude/worktrees/<value>/. Жобаңыз ~/dev/my-app/ ішінде болса, feature-auth worktree-і ~/dev/my-app/.claude/worktrees/feature-auth/ ішінде болады.

Стандартты емес құрылымдар үшін (мысалы, worktree-ді репозиторийден тыс жерде сақтағыңыз келсе) WorktreeCreate хугы бар — бұл туралы төмендегі SVN және Mercurial туралы бөлімде айтылады.

Бір Claude сессиясының ішінде басқа бар worktree-ге ауысуға болады. Чатта: “.claude/worktrees/bugfix-123 тармағына ауыс” деп айтыңыз, сонда Claude EnterWorktree құралын шақырады. Ағымдағы қалта өзгеріссіз қалады — кері де осылай қайтуға болады.

Стандартты Git пәрмені негізгі worktree мен қолмен жасалған worktree-лерді қоса, барлығын көрсетеді:

git worktree list

Нәтиже мынадай болады:

/home/user/dev/my-app                  abc1234 [main]
/home/user/dev/my-app/.claude/worktrees/feature-auth  def5678 [worktree-feature-auth]
/home/user/dev/my-app/.claude/worktrees/bugfix-123    9876fed [worktree-bugfix-123]

.env пен құпияларды көшіру: .worktreeinclude файлы#

--worktree жаңа қалта жасағанда, оған тек Git-ке commit жасалған нәрсе ғана түседі. API кілттері бар .env пен жергілікті баптаулары бар .env.local файлдары .gitignore тізімінде, сондықтан worktree-де болмайды. Алғашқы npm run dev бірден “MISSING DATABASE_URL” қатесімен аяқталады.

Үйде жасалған шешім — әр --worktree-ден кейін .env файлын қолмен көшіру. Бір рет жұмыс істейді, кейін ұмытылып кетеді. Anthropic шешімі — жоба түбіріндегі .worktreeinclude файлына Git бақылайтын файлдардың ішінен көшіру керек файлдарды тізіп, әр жаңа worktree-ге автоматты көшіру.

Репозиторий түбірінде .worktreeinclude файлын жасаңыз:

.env
.env.local
config/secrets.json

Синтаксисі .gitignore синтаксисімен бірдей. Glob үлгілерін қолдануға болады:

.env*
*.local
config/*.json
.vscode/settings.json

Anthropic кездейсоқ жағдайлардың алдын алатын нақты ереже ұсынады:

Басқаша айтқанда, .worktreeinclude арқылы package.json файлын кездейсоқ көшіру мүмкін емес — ол .gitignore ішінде жоқ. Мұнда кез келген үлгіні қауіпсіз көрсетуге болады.

Дәл осы .worktreeinclude үш режимде жұмыс істейді: қолмен іске қосылатын --worktree, субагенттерге арналған автоматты worktree-лер (төменде қараңыз) және Claude жұмыс үстелі қолданбасындағы сессиялар.

Кодты шолу үшін pull request-тен worktree жасау#

Кодты шолудың қалыпты жағдайы: әріптесіңіз PR жіберді; кодты қарап, тестілерді іске қосып, пікір қалдыру керек. Кәдімгі git checkout pull/1234/head пәрменімен жұмыс көшірмесін қайта ауыстырып, белсенді сессияңызды бұзасыз.

--worktree жалаушасымен бұл бір пәрменмен орындалады:

claude --worktree "#1234"

Не болады: Claude Code git fetch origin pull/1234/head пәрменін іске қосып, .claude/worktrees/pr-1234/ ішінде worktree жасап, PR тармағына өтеді. Сессия басталады. Бірден одан “diff-ті оқып, тестілерді іске қосып, логикалық қателерді табуды” сұрай аласыз — Claude жұмыс істеп жатқанда, main тармағындағы негізгі сессияңыз жұмысын жалғастырады.

Баламалы синтаксисі — pull request-тің толық URL мекенжайы:

claude --worktree https://github.com/OWNER/REPO/pull/1234

Нақты жобада қолдану: claude --worktree "#N" пәрменін өзіңіздің code-reviewer субагентіңізбен жұптастыру автоматты шолуды бір-екі минутта алуға мүмкіндік береді. Оны фондық режимде іске қосып, негізгі терезеде жұмысты жалғастырыңыз да, нәтижеге claude agents арқылы оралыңыз.

Негізгі тармақ: fresh немесе head үшін worktree.baseRef#

Әдепкі баптау мынадай: әр жаңа worktree origin/HEAD күйінен басталады. Артықшылығы — CI көретін күймен сәйкес келетіні кепілденген таза бастама. Кемшілігі — ағымдағы тармақта commit жасалмаған өзгерістеріңіз немесе қашықтағы репозиторийден артық бірнеше жергілікті commit болса, олар жаңа worktree-ге кірмейді.

Worktree-ді ағымдағы жергілікті HEAD коммитінен бастау үшін .claude/settings.json файлына (немесе жаһандық баптауларға) мынаны қосыңыз:

{
  "worktree": {
    "baseRef": "head"
  }
}

Енді claude --worktree experimental-feature ағымдағы жергілікті HEAD коммитінен басталады. Бұл мүмкіндікке push жасалмаған жергілікті коммиттер бар кезде пайдалы. Ол әлі коммиттелмеген бақыланатын өзгерістерді қоспайды. Субагентке сол өзгерістер керек болса, қажеттерін сақтап, анық көшіріңіз де, нысанадағы diff-ті қараңыз; мұны еленбейтін жергілікті файлдарға арналған .worktreeinclude механизмімен шатастырмаңыз.

Баптау дәл екі мәнді қабылдайды: "fresh" (= origin/HEAD) және "head" (= жергілікті HEAD). "feature-branch" немесе commit хэші сияқты кез келген ref жарамайды — мүмкіндіктердің шамадан тыс көбеюіне жол бермеу үшін бұл әдейі қойылған шектеу.

Субагенттерді автоматты оқшаулау: isolation: worktree#

Claude-қа “үш субагентті іске қос: біріншісі дерекқорды оқысын, екіншісі API-ді қарасын, үшіншісі тестілерді тексерсін” десеңіз, үшеуі де әдепкіде жұмыс көшірмеңізде жұмыс істейді. Тіпті екеуі бір файлға бір уақытта жазса да, қайшылық туады. Шешімі — әрқайсысына өз worktree-сін автоматты түрде беру.

1-әдіс: ауызша сұрау. Claude-пен әңгімеде былай деп жазыңыз:

Агенттеріңіз үшін worktree пайдаланыңыз.

Claude осы сессияда бұдан кейінгі барлық субагенттерге оқшаулауды қолданады.

2-әдіс: оны субагенттің өзіне нақты көрсету. Субагент файлында (мысалы, .claude/agents/code-reviewer.md) frontmatter бөлігіне өріс қосыңыз:

---
name: code-reviewer
description: Reads the diff and writes code review comments
isolation: worktree
---

You're a meticulous reviewer. Read the diff and look for logic errors...

Енді бұл субагентті әр іске қосқанда .claude/worktrees/ ішінде уақытша worktree ашылады. Егер субагент ештеңе жазбаса, жұмысын аяқтағанда қалта автоматты түрде жойылады. Commit жасалмаған өзгерістер болса, Claude оларды сақтауды немесе жоюды сұрайды.

Субагент worktree-лерінің бастапқы тармағы --worktree жағдайындағыдай: әдепкіде origin/HEAD, ал worktree.baseRef: head орнатылса, жергілікті HEAD.

Шешімдер матрицасы: worktree, /bg, субагент немесе Agent View#

Әдеттегі үйлесімдер:

• “2 мүмкіндік қатар, қолмен” — екі терминалдың әрқайсысында claude --worktree іске қосылады. Ең қарапайым жағдай.
• “Түн бойы рефакторинг жүрсін, қолданбаны жабамын” — аяқталу шарты бар /bg + /goal. Сессия терезеңізден тәуелсіз жұмыс істейді.
• “Бір сұрау мәтіні, үш қатар зерттеу” — isolation: worktree орнатылған үш субагент. Әрқайсысы өз оқшауланған ортасында.
• “Қазір не іске қосулы?” — claude agents. “running,” “blocked” және “done” сүзгілері бар барлық сессиялардың бақылау тақтасы.

Worktree-мен жұмыс істегенде кездесетін 5 кедергі#

1. Worktree іске қосылды, .env жоқ, ештеңе жұмыс істемейді. Ең жиі кездесетін мәселе. Worktree — Git бақылайтын файлдары жоқ жаңадан жасалған checkout. Шешімі: worktree режимін баптаған бойда .env* және қажетті жергілікті баптаулары бар .worktreeinclude файлын қосыңыз. Файл .claude/ ішінде емес, репозиторий түбірінде тұрғанын тексеріңіз.

2. Негізгі тармаққа ауысқыңыз келіп, түбірге cd іске қосып, worktree-дегі commit жасалмаған өзгерістеріңізді жоғалттыңыз. Түбірлік қалта мен worktree — екі түрлі жұмыс көшірмесі. cd арқылы кері қайттыңыз; worktree-дегі өзгерістер сол қалпында қалды — ешқайда кеткен жоқ. Бірақ шатасып, worktree-десіз деп ойлап негізгі қалтада git stash пәрменін іске қоссаңыз, stash күткен тармағыңызда емес, негізгі тармақта жасалады.

3. 5 параллель сессия іске қосып, әрқайсысы не істеп жатқанын еске түсіре алмадыңыз. Anthropic құжаттамасында әзірлеушілердің көпшілігі 2–3 сессиядан артықты ойша қатар басқара алмайтыны анық ескертіледі. Agent View-ді ашқанда әр агенттің не істеп жатқанын бірден айта алмау — артық жүктеменің белгісі. Бір мезетте екі сессиямен шектеліңіз. Тапсырма көбірек сессия талап етсе, оларды қолмен емес, /goal + субагенттер арқылы үйлестіру керек.

4. -p арқылы іске қосылған (headless) worktree-лер автоматты тазаланбайды. claude --worktree feature-x -p "do thing" пәрмені интерактивті шығу сұрауын көрсетпейді, сондықтан Claude “worktree-ді жою керек пе?” деп сұрайтын сәт болмайды. Ондай worktree-лер жинала береді. Қолмен тазалаңыз: git worktree remove .claude/worktrees/feature-x. Немесе 7 күннен асқан кез келгенін жоятын cron скриптін қолданыңыз.

5. Жаңа қалтадағы сенім диалогы. Репозиторийді алғаш ашқанда бірден claude --worktree іске қоссаңыз, пәрмен орындалмайды. claude пәрменін жалаушаларсыз іске қосып, жұмыс кеңістігіне сенімді растаңыз да, шығыңыз — содан кейін --worktree жұмыс істейді. Бұл әдейі жасалған: Claude пайдаланушының келісімінсіз біреудің жобасына кіре алмайды.

Тазалау: не автоматты түрде жойылады#

Тазалау тәртібі worktree-де не істегеніңізге және сессияны қалай бастағаныңызға байланысты. Anthropic құжаттамасында үш жағдай көрсетілген:

1-жағдай: кірдіңіз, ештеңе істемей шығып кеттіңіз — worktree жойылды.

2-жағдай: біраз жұмыс істеп, commit жасамадыңыз — шыққанда Claude “сақтау керек пе, әлде жою керек пе?” деп сұрайды. “Сақтау” қалта мен тармақты кейінге қалдырады. “Жою” каталогты онымен бірге commit жасалмаған өзгерістер мен жаңа commit-терді де жояды. Бұл — қайтымсыз әрекет, әдетпен “жою” түймесін баспаңыз.

3-жағдай: -p арқылы (headless) іске қосып, пәрмен аяқталған соң шықтыңыз. Worktree орнында қалады. Оны қолмен тазалаңыз:

git worktree remove .claude/worktrees/feature-x

Бұған қоса, субагенттер мен /bg сессиялары жасаған worktree-лер, егер cleanupPeriodDays күнінен ескі болса (бұл баптау, әдетте әдепкіде 30 күн) және сақталмаған жұмысы болмаса, фондық тазалау кезінде автоматты түрде жойылады. --worktree жасаған worktree-лер автоматты тазалауға кірмейді — оларға өзіңіз жауап бересіз.

SVN, Perforce және Mercurial баламалары: WorktreeCreate хугы#

Репозиторий Subversion немесе Mercurial пайдаланса, --worktree жалаушасы тікелей жұмыс істемейді. Anthropic екі хук арқылы кеңейту нүктесін ұсынады: WorktreeCreate (оқшауланған көшірме жасайды) және WorktreeRemove (оны жояды).

Ресми құжаттамадан алынған SVN хугының мысалы:

{
  "hooks": {
    "WorktreeCreate": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "bash -c 'NAME=$(jq -r .name); DIR=\"$HOME/.claude/worktrees/$NAME\"; svn checkout https://svn.example.com/repo/trunk \"$DIR\" >&2 && echo \"$DIR\"'"
          }
        ]
      }
    ]
  }
}

Хук worktree атауын stdin-нен оқиды ({ "name": "feature-auth" }), svn checkout пәрменін алдын ала есептелген каталогта іске қосып, жолды stdout-қа шығарады — Claude Code оны жаңа сессияның жұмыс каталогы ретінде пайдаланады.

Маңызды ескерту: өз хугыңызды қолданғанда .worktreeinclude пайдаланылмайды. Жаңа қалтада .env немесе Git елемейтін басқа файлдар керек болса, оларды хук скриптінің ішінде көшіріңіз.

Келесі қадам: қатар жұмысты қамтамасыз ететін үш тетік#

Worktree файлдарды оқшаулайды. /bg контексті оқшаулайды. Субагенттер тапсырмаларды оқшаулайды. Әр тетік жеке бір мәселені шешеді. Бірге қолданғанда, ойша шамадан тыс жүктелмей, қатарынан үш-бес тапсырманы орындауға мүмкіндік береді. Бұл — 2026 жылғы озық vibe-coding-тің негізіндегі дағдылар жиынтығы.

Бұл тақырып үш байланысты тақырыпқа табиғи түрде ұласады: /goal және Agent View арқылы автономды агентті қалай баптау керек, өз тапсырмаларыңызға арналған субагенттерді қалай жасау керек және Dynamic Workflows арқылы жүздеген агентті қалай іске қосу керек.

Ailoot-ты ашыңыз.