merge-helper
合并功能分支到主分支,进行预合并检查、更新CHANGELOG和架构。当所有规格阶段完成且用户希望合并时使用。确保合并前质量关卡通过。
name: merge-helper description: Merge feature branch to main with pre-merge checks, CHANGELOG and ARCHITECTURE updates. Use when all spec stages are complete and user wants to merge. Ensures quality gates pass before merge.
Merge Helper Skill
You guide the process of merging a completed feature branch into main.
When to Use This Skill
- All stages in spec are ✅ Завершён
- User asks to "merge to main" or "мерж в main"
- Feature is ready for integration
- PR needs to be prepared
Prerequisites
Before merge:
- All spec stages must be ✅
- All tests must pass
- No uncommitted changes
- Branch is up to date with main
Workflow
Step 1: Verify Feature Completion
Load spec file and check:
branch=$(git branch --show-current)
spec_file=".ai/specs/${branch}.md"
Verify all stages are ✅:
Checking feature completion...
Spec: .ai/specs/{branch}.md
Stages: 5/5 ✅
All stages complete. Proceeding with merge preparation.
If incomplete stages exist:
⚠️ Фича не завершена
Незавершённые этапы:
- Этап 3: API endpoints (🔄 В работе)
- Этап 4: UI templates (⬜ Не начат)
Завершите все этапы перед мержем.
STOP — do not proceed.
Step 2: Run Quality Checks
# Run all tests
uv run pytest
# Check for uncommitted changes
git status
# Check if branch is behind main
git fetch origin main
git log HEAD..origin/main --oneline
If tests fail:
❌ Тесты не проходят
Failed: 3, Passed: 47
Исправьте тесты перед мержем.
STOP
If uncommitted changes:
⚠️ Есть незакоммиченные изменения
Modified files:
- src/module/file.py
- tests/test_file.py
Закоммитьте или отмените изменения.
STOP
If behind main:
⚠️ Ветка отстаёт от main
Commits behind: 5
Обновите ветку:
git rebase origin/main
# или
git merge origin/main
Step 3: Update CHANGELOG
Read .ai/CHANGELOG.md and add release entry:
## [Unreleased]
### Added - {Feature Name}
- [path/to/file1.py](../path/to/file1.py): Description
- Detail 1
- Detail 2
### Changed
- [path/to/file2.py](../path/to/file2.py): What changed
### Fixed
- [path/to/file3.py](../path/to/file3.py): What was fixed
Collect changes from all commits in branch:
git log main..HEAD --oneline
Step 4: Update ARCHITECTURE (if needed)
Check if architectural changes were made:
- New modules added?
- New services/dependencies?
- Database schema changes?
- API surface changes?
If yes, update .ai/ARCHITECTURE.md:
- Add new components to diagrams
- Update module descriptions
- Document new patterns
Step 5: Final Spec Update
Update spec file status:
# [Feature Name] - Feature Specification
> **Дата создания:** 2026-01-05
> **Дата завершения:** 2026-01-07 ← Add this
> **Ветка:** `feature/name`
> **Статус:** ✅ Завершён ← Change from 🟡
Add final history entry:
| 2026-01-07 | MERGE | abc1234 | Feature merged to main |
Step 6: Prepare Merge
Option A: Squash Merge (recommended)
git checkout main
git pull origin main
git merge --squash feature/{name}
git commit -m "feat: {feature description}
- Stage 1: {description}
- Stage 2: {description}
- ...
Closes #{issue-number}"
Option B: Rebase Merge
git checkout main
git pull origin main
git rebase feature/{name}
Step 7: Post-Merge Cleanup
After successful merge:
# Delete local branch
git branch -d feature/{name}
# Delete remote branch (if applicable)
git push origin --delete feature/{name}
Archive spec file (optional):
mv .ai/specs/{branch}.md .ai/specs/archive/{branch}.md
Step 8: Report Completion
✅ Merge завершён
📋 Фича: {Feature Name}
🌿 Ветка: feature/{name} → main
📝 Коммит: {commit-hash}
📄 Обновлённые документы:
- .ai/CHANGELOG.md ✅
- .ai/ARCHITECTURE.md ✅ (если применимо)
- .ai/specs/{branch}.md → archived
🧹 Cleanup:
- Локальная ветка удалена ✅
- Remote ветка удалена ✅
Фича успешно интегрирована в main!
Pre-Merge Checklist
Before proceeding with merge, verify:
- All spec stages ✅
- All tests pass
- No uncommitted changes
- Branch up to date with main
- CHANGELOG updated
- ARCHITECTURE updated (if needed)
- Spec marked as complete
- User confirmed merge
Merge Strategies
When to Squash
- Feature has many small commits
- Commit history is messy
- Want clean single commit in main
When to Rebase
- Commits are well-structured
- Want to preserve commit history
- Each commit is atomic and meaningful
References
See commit-helper for commit conventions. See changelog_templates.md for CHANGELOG format.
NOTE: This is the ONLY place where CHANGELOG.md should be updated. Individual commits do NOT update CHANGELOG.