Sync-Main

Sync-Main

Overview

每天开工前同步 main 分支：拉最新代码 → 报告变动 → 影响分析 → 重建环境 → 启动。只看不动，功能完成后再合并。

团队架构参考: https://lucian-why.github.io/team-skills/team-architecture.html

Core principle: 先看别人干了什么，再决定怎么开工。不改你的分支，不 rebase，不 merge。

Announce at start: "I'm using the sync-main skill to sync with main and start dev environment."

When to Use

• 每天开工前（继续开发已有分支时）
• 隔了几天没写代码，想看看 main 有什么新东西
• 触发词："开工" / "同步" / "sync" / "看看 main 有什么更新"

When NOT to Use

• 开新功能 → 用 start-feature（已经包含拉最新 main）
• 功能完成准备推代码 → 用 pre-push（包含 rebase/merge 和冲突处理）

The Process

Step 1: Fetch and Compare

git fetch origin main

BRANCH=$(git branch --show-current)
BEHIND=$(git rev-list HEAD..origin/main --count)
AHEAD=$(git rev-list origin/main..HEAD --count)

If behind is 0:

✅ 你的分支 feature/chat 已经是最新，领先 main 2 个 commit。
   直接开工：docker-compose up

Skip to Step 4.

If behind > 0: Continue to Step 2.

Step 2: Generate Sync Report

# 获取 main 上的变动（自你分支分叉以来的 commit）
git log HEAD..origin/main --pretty=format:"%h|%an|%s" --no-merges

输出格式：

═══════════════════════════════════════
         sync-main 报告
═══════════════════════════════════════

📍 你的分支 feature/chat 落后 main 5 个 commit

📝 main 变动：
  abc1234 @张三 — feat: 新增学习路径推荐算法
    └ shared/ai/model.ts, features/learning-path/service/recommend.ts
  def5678 @李四 — fix: 登录页样式错位
    └ features/auth/components/LoginForm.tsx
  ghi9012 @王五 — chore: 升级 React 19
    └ package.json, package-lock.json, Dockerfile

Step 3: Impact Analysis

检查变动文件，分类标记影响级别：

# 检查 shared/ 有没有变动
git diff --name-only HEAD..origin/main | grep "^shared/"

# 检查依赖文件有没有变动
git diff --name-only HEAD..origin/main | grep -E "package\.json|Dockerfile|docker-compose"

输出影响分析：

⚠️ 影响分析：
  🔴 shared/ai/ 有变动 → 你用到了 ai/ 的接口，注意兼容性
  🔴 shared/frontend/ui/ 有变动 → 通用组件更新了
  🔴 package.json 变了 → 需要 docker-compose build
  🟡 Dockerfile 变了 → 建议 docker-compose build --no-cache
  🟢 features/auth/ 改动 → 不影响你的 feature/chat

判断逻辑：

• 🔴 红色：shared/ 下有文件变动，或 package.json/Dockerfile 变动
• 🟡 黄色：Dockerfile 变动（建议 --no-cache）
• 🟢 绿色：只改了其他 feature 目录，不影响你

注意： 这里只是提醒你别人改了什么。你不需要现在合并或 rebase，功能完成后再用 pre-push 处理合并。

Step 4: Rebuild and Start

# 用 main 最新代码重建 Docker 镜像并启动
docker-compose up --build

输出：

🚀 用 main 最新代码启动环境...
   前端: http://localhost:5173
   后端: http://localhost:3000

✅ 环境就绪，浏览器打开确认一下。

为什么每次都 build？ main 上可能有新提交，镜像需要更新。这一步保证你跑的是最新代码构建的环境，不是你本地旧镜像。

Step 5: Verify

浏览器打开 http://localhost:5173，确认页面能正常加载。
如果有问题，检查 docker-compose logs 输出。

Quick Reference

场景	执行
落后 0 commit	跳过，直接 docker-compose up
落后 + 无 shared/ 变动	看报告 → docker-compose up --build
落后 + shared/ 变动	看报告 + 影响分析 → docker-compose up --build
落后 + 依赖变动	看报告 → docker-compose up --build
功能完成要合并	用 pre-push，不用 sync-main

Common Mistakes

不检查就开工

• Problem: 写了半天代码，不知道 main 上别人改了 shared/，后面合并才发现不兼容
• Fix: 每天开工先跑 sync-main

在 sync-main 里做 rebase/merge

• Problem: 功能没完成就合并 main，引入不必要的冲突和复杂度
• Fix: sync-main 只负责看报告，合并是 pre-push 的事

忽略 🔴 影响警告

• Problem: shared/ 改了你没注意，写了一天代码发现接口不兼容
• Fix: 看完影响分析再开工，提前知道哪些接口变了

Red Flags

Never:

• 跳过 sync 直接写代码（不知道 main 变了什么）
• 功能没完成就 rebase/merge main（合并是 pre-push 的事）

Always:

• 开工前先 sync-main
• 看完影响分析再决定要不要改自己的代码
• shared/ 有变动时检查自己的 import 是否还兼容

Integration

Pairs with:

• start-feature — 开新功能用 start-feature，继续开发用 sync-main
• sync-shared — 你改了 shared/ 用 sync-shared 通知别人，别人改了 shared/ 用 sync-main 知道
• pre-push — sync-main 负责看报告，pre-push 负责合并和推送