auto-claude-workspace

用途

Auto-Claude Workspace 管理用于处理 git worktree 隔离、分支管理与合并操作。当需要审查变更、合并构建、管理分支或理解隔离策略时使用。核心目标是让每次构建都在完全隔离的环境中进行，不干扰主分支。

工作区架构与分支策略

Auto-Claude 使用 git worktrees 实现完整隔离。项目结构中包含 .git 主目录、项目文件、.auto-claude/（含 .auto-claude/specs/ spec 定义）以及 .worktrees/ 隔离工作区目录，例如 .worktrees/auto-claude/001-feature/。

分支策略上，每个 spec 对应一个隔离分支，命名如 auto-claude/{spec-name}。关键原则：每个 spec 一个分支；所有变更都在隔离 worktree 中进行；不会自动推送到远程；由用户控制何时合并或推送。

主要能力与使用方式

审查变更：进入 apps/backend，运行 python run.py --spec 001 --review。输出显示已更改文件、增删行以及提交历史。

在 worktree 中测试：进入 .worktrees/auto-claude/001-feature/，使用项目自身的运行命令（如 npm run dev、python manage.py runserver）启动并测试功能，之后返回 backend。

合并变更：运行 python run.py --spec 001 --merge，会检查冲突、将 auto-claude/001-feature 合并到当前分支、在存在冲突时使用 AI 解决器，并清理 worktree。

丢弃构建：运行 python run.py --spec 001 --discard，会请求确认、删除 worktree 和分支，并可选保留 spec 以供参考。

手动 worktree 操作：可通过 git worktree add .worktrees/experiment -b experiment-branch 创建、在目录中工作，再用 git worktree remove .worktrees/experiment 清理；用 git worktree list 列出，用 git worktree prune 清理失效项。

冲突解决：Auto-Claude 使用 AI 解决合并冲突，流程为检测冲突文件、理解双方版本、智能合并、验证结果。若 AI 合并失败，可进入 worktree 执行 git merge main，在编辑器中手动解决冲突，git add . 与 git commit 后返回 backend，再执行 --merge。

分支管理：用 git branch -a 查看所有分支，git branch | grep auto-claude 查看 auto-claude 分支；用 git branch -d auto-claude/old-feature 删除本地分支，git push origin --delete auto-claude/old-feature 删除远程分支；可在 apps/backend/.env 中设置默认基础分支，如 echo "DEFAULT_BRANCH=develop" >> apps/backend/.env。

工作区数据与隔离

worktree 元数据可查看 .auto-claude/specs/001-feature/worktree.json，其中包含 worktree_path、branch_name、base_branch、created_at、status 字段。每个 worktree 完全隔离：独立工作目录、独立 git 索引、必要时独立 node_modules，且不干扰主分支。

最佳实践

合并前：充分审查变更（--review）、在 worktree 中测试（npm test、npm run build）、检查冲突（git diff main...auto-claude/001-feature）。合并后：运行完整测试套件、验证功能、就绪后提交并推送。定期清理旧 worktree。

故障排查

worktree 已存在时，先 git worktree remove 再重试构建；分支已存在时，先 git branch -D 再重试；合并冲突可手动解决；worktree 损坏时用 git worktree remove --force、git worktree prune，删除 spec 后重新运行 python spec_runner.py --task "Your task"。

技能介绍

用途