modernize

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Modernize (Brownfield Upgrade)

现代化改造（遗留系统升级）

Optional Step after Gear 6 for Brownfield projects with

modernize: true

flag.

Estimated Time: 2-6 hours (depends on dependency age and breaking changes) Prerequisites: Gears 1-6 completed, 100% spec coverage established Output: Modern dependency versions, updated tests, synchronized specs

可选步骤：针对启用

modernize: true

标志的遗留系统项目，在完成Gear 6步骤后执行。

预计耗时：2-6小时（取决于依赖项的老旧程度和破坏性变更数量） 前置条件：已完成Gear 1-6步骤，已建立100%的规范覆盖率 输出结果：现代化的依赖版本、更新后的测试用例、同步后的规范文档

When to Use This Skill

何时使用该技能

Use this skill when:

Brownfield path with
```
modernize: true
```
flag set
Gears 1-6 are complete (specs established, gaps implemented)
Ready to upgrade all dependencies to latest versions
Want to modernize while maintaining spec-driven control

Trigger Conditions:

State file has
```
path: "brownfield"
```
AND
```
modernize: true
```
Gear 6 (implement) is complete
User requested "Brownfield Upgrade" during Gear 1

在以下场景使用该技能：

采用遗留系统路径且设置了
```
modernize: true
```
标志
已完成Gear 1-6步骤（已建立规范、填补了实现缺口）
准备将所有依赖项升级至最新版本
希望在保持规范驱动控制的前提下实现应用现代化

触发条件：

状态文件中包含
```
path: "brownfield"
```
且
```
modernize: true
```
Gear 6（实现阶段）已完成
用户在Gear 1阶段请求了“遗留系统升级”

What This Skill Does

该技能的作用

Systematically upgrades the entire application to modern dependency versions:

Detect Package Manager - npm, yarn, pnpm, pip, go mod, cargo, etc.
Audit Current Versions - Document what's installed before upgrade
Upgrade Dependencies - Use appropriate upgrade command for tech stack
Run Tests - Identify breaking changes
Fix Breaking Changes - Iteratively fix with spec guidance
Update Specs - Synchronize specs with API/behavior changes
Validate Coverage - Ensure tests meet 85%+ threshold
Verify Specs Match - Run /speckit.analyze to confirm alignment

系统性地将整个应用升级至现代化的依赖版本：

检测包管理器 - npm、yarn、pnpm、pip、go mod、cargo等
审计当前版本 - 在升级前记录已安装的依赖项信息
升级依赖项 - 针对技术栈使用合适的升级命令
运行测试 - 识别破坏性变更
修复破坏性变更 - 借助规范指导逐步修复问题
更新规范 - 同步规范文档以匹配API/行为变更
验证覆盖率 - 确保测试覆盖率达到85%以上的阈值
验证规范匹配度 - 运行/speckit.analyze以确认规范与实现一致

Process Overview

流程概述

Phase 1: Pre-Upgrade Audit

阶段1：升级前审计

Document current state:

bash

undefined

记录当前状态：

bash

undefined

Create upgrade baseline

创建升级基准

cat package.json > .modernize/baseline-package.json

Run tests to establish baseline

运行测试以建立基准

npm test > .modernize/baseline-test-results.txt

Document current coverage

记录当前覆盖率

npm run test:coverage > .modernize/baseline-coverage.txt


**Analyze upgrade scope**:
```bash

npm run test:coverage > .modernize/baseline-coverage.txt


**分析升级范围**：
```bash

Check for available updates

检查可用更新

npm outdated > .modernize/upgrade-plan.txt

Identify major version bumps (potential breaking changes)

识别大版本更新（可能存在破坏性变更）

Highlight security vulnerabilities

高亮安全漏洞

Note deprecated packages

标记已废弃的包

---

---

Phase 2: Dependency Upgrade

阶段2：依赖项升级

Tech stack detection (from analysis-report.md):

For Node.js/TypeScript:

bash

undefined

技术栈检测（来自analysis-report.md）：

针对Node.js/TypeScript：

bash

undefined

Update all dependencies

更新所有依赖项

npm update

Or for major versions:

或者针对大版本更新：

npx npm-check-updates -u npm install

Check for security issues

检查安全问题

npm audit fix


**For Python**:
```bash

npm audit fix


**针对Python**：
```bash

Update all dependencies

更新所有依赖项

pip install --upgrade -r requirements.txt pip freeze > requirements.txt

Or use pip-upgrader

或者使用pip-upgrader

pip-upgrade requirements.txt


**For Go**:
```bash

pip-upgrade requirements.txt


**针对Go**：
```bash

Update all dependencies

更新所有依赖项

go get -u ./... go mod tidy


**For Rust**:
```bash

go get -u ./... go mod tidy


**针对Rust**：
```bash

Update dependencies

更新依赖项

cargo update

Check for outdated packages

检查过时包

cargo outdated

---

cargo outdated

---

Phase 3: Breaking Change Detection

阶段3：破坏性变更检测

Run tests after upgrade:

bash

undefined

升级后运行测试：

bash

undefined

Run full test suite

运行完整测试套件

npm test

Capture failures

捕获失败结果

npm test 2>&1 | tee .modernize/post-upgrade-test-results.txt

Compare to baseline

与基准结果对比

diff .modernize/baseline-test-results.txt .modernize/post-upgrade-test-results.txt


**Identify breaking changes**:
- TypeScript compilation errors
- Test failures
- Runtime errors
- API signature changes
- Deprecated method usage

---

diff .modernize/baseline-test-results.txt .modernize/post-upgrade-test-results.txt


**识别破坏性变更**：
- TypeScript编译错误
- 测试用例失败
- 运行时错误
- API签名变更
- 已废弃方法的使用

---

Phase 4: Fix Breaking Changes (Spec-Guided)

阶段4：修复破坏性变更（规范指导）

For each breaking change:

Identify affected feature:
- Match failing test to feature spec
- Determine which spec the code implements
Review spec requirements:
- What behavior SHOULD exist (from spec)
- What changed in the upgrade
- How to preserve spec compliance
Fix with spec guidance:
- Update code to work with new dependency
- Ensure behavior still matches spec
- Refactor if needed to maintain spec alignment
Update tests:
- Fix broken tests
- Add tests for new edge cases from upgrade
- Maintain 85%+ coverage threshold
Verify spec alignment:
- Behavior unchanged from user perspective
- Implementation may change but spec compliance maintained

针对每个破坏性变更：

识别受影响的功能：
- 将失败的测试用例与功能规范关联
- 确定代码实现的是哪项规范
查看规范要求：
- （根据规范）应该存在的行为是什么
- 升级带来了哪些变更
- 如何保持规范合规性
借助规范指导修复：
- 更新代码以适配新依赖项
- 确保行为仍符合规范要求
- 如有需要，重构代码以保持与规范的一致性
更新测试用例：
- 修复失败的测试用例
- 为升级带来的新边缘场景添加测试
- 保持85%以上的覆盖率阈值
验证规范一致性：
- 从用户视角看行为无变化
- 实现方式可能变更，但需保持规范合规

Phase 5: Spec Synchronization

阶段5：规范同步

Check if upgrades changed behavior:

Some dependency upgrades change API behavior:

Date formatting libraries (moment → date-fns)
Validation libraries (joi → zod)
HTTP clients (axios → fetch)
ORM updates (Prisma major versions)

If behavior changed:

Update relevant feature spec to document new behavior
Update acceptance criteria if needed
Update technical requirements with new dependencies
Run /speckit.analyze to validate changes

If only implementation changed:

No spec updates needed
Just update technical details (versions, file paths)

检查升级是否改变了行为：

部分依赖项升级会改变API行为：

日期格式化库（moment → date-fns）
验证库（joi → zod）
HTTP客户端（axios → fetch）
ORM更新（Prisma大版本）

若行为发生变更：

更新相关功能规范以记录新行为
如有需要，更新验收标准
更新技术要求以包含新依赖项
运行/speckit.analyze以验证变更

若仅实现方式变更：

无需更新规范内容
仅需更新技术细节（版本、文件路径）

Phase 6: Test Coverage Improvement

阶段6：测试覆盖率提升

Goal: Achieve 85%+ coverage on all modules

Run coverage report:
bash
```
npm run test:coverage
```
Identify gaps:
- Modules below 85%
- Missing edge case tests
- Integration test gaps
Add tests with spec guidance:
- Each spec has acceptance criteria
- Write tests to cover all criteria
- Use spec success criteria as test cases

Validate:

bash

npm run test:coverage
# All modules should be 85%+

目标：所有模块的测试覆盖率达到85%以上

生成覆盖率报告：
bash
```
npm run test:coverage
```
识别缺口：
- 覆盖率低于85%的模块
- 缺失的边缘场景测试
- 集成测试缺口
借助规范指导添加测试：
- 每项规范都有验收标准
- 编写测试用例以覆盖所有标准
- 将规范的成功标准作为测试用例

验证：

bash

npm run test:coverage
# 所有模块覆盖率应≥85%

Phase 7: Final Validation

阶段7：最终验证

Run complete validation suite:

Build succeeds:
bash
```
npm run build
# No errors
```
All tests pass:
bash
```
npm test
# 0 failures
```

Coverage meets threshold:

bash

npm run test:coverage
# 85%+ on all modules

Specs validated:

bash

/speckit.analyze
# No drift, all specs match implementation

Dependencies secure:

bash

npm audit
# No high/critical vulnerabilities

运行完整验证套件：

构建成功：
bash
```
npm run build
# 无错误
```
所有测试通过：
bash
```
npm test
# 0个失败用例
```

覆盖率达到阈值：

bash

npm run test:coverage
# 所有模块覆盖率≥85%

规范验证通过：

bash

/speckit.analyze
# 无偏差，所有规范与实现一致

依赖项安全：

bash

npm audit
# 无高/严重级安全漏洞

Output

输出结果

Upgrade Report (

.modernize/UPGRADE_REPORT.md

markdown

undefined

升级报告（

.modernize/UPGRADE_REPORT.md

）：

markdown

undefined

Dependency Modernization Report

依赖项现代化报告

Date: {date} Project: {name}

日期：{date} 项目：{name}

Summary

摘要

Dependencies upgraded: {X} packages
Major version bumps: {X} packages
Breaking changes: {X} fixed
Tests fixed: {X} tests
New tests added: {X} tests
Coverage improvement: {before}% → {after}%
Specs updated: {X} specs

已升级依赖项：{X}个包
大版本更新：{X}个包
已修复破坏性变更：{X}个
已修复测试用例：{X}个
新增测试用例：{X}个
覆盖率提升：{before}% → {after}%
已更新规范：{X}项

Upgraded Dependencies

已升级的依赖项

Package	Old Version	New Version	Breaking?
react	17.0.2	18.3.1	Yes
next	13.5.0	14.2.0	Yes
...	...	...	...

包名	旧版本	新版本	是否存在破坏性变更
react	17.0.2	18.3.1	是
next	13.5.0	14.2.0	是
...	...	...	...

Breaking Changes Fixed

已修复的破坏性变更

React 18 Automatic Batching
- Affected: User state management
- Fix: Updated useEffect dependencies
- Spec: No behavior change
- Tests: Added async state tests
Next.js 14 App Router
- Affected: Routing architecture
- Fix: Migrated pages/ to app/
- Spec: Updated file paths
- Tests: Updated route tests

React 18 自动批处理
- 受影响范围：用户状态管理
- 修复方式：更新useEffect依赖项
- 规范：行为无变更
- 测试：新增异步状态测试用例
Next.js 14 App Router
- 受影响范围：路由架构
- 修复方式：将pages/迁移至app/
- 规范：更新文件路径
- 测试：更新路由测试用例

Spec Updates

规范更新

Updated technical requirements with new versions
Updated file paths for App Router migration
No functional spec changes (behavior preserved)

更新技术要求以包含新版本
更新App Router迁移后的文件路径
无功能规范变更（行为保持不变）

Test Coverage

测试覆盖率

Before: 78%
After: 87%
New tests: 45 tests added
All modules: ✅ 85%+

升级前：78%
升级后：87%
新增测试用例：45个
所有模块：✅ 覆盖率≥85%

Validation

验证结果

✅ All tests passing
✅ Build successful
✅ /speckit.analyze: No drift
✅ npm audit: 0 high/critical
✅ Coverage: 87% (target: 85%+)

✅ 所有测试通过
✅ 构建成功
✅ /speckit.analyze：无偏差
✅ npm audit：0个高/严重级漏洞
✅ 覆盖率：87%（目标：≥85%）

Next Steps

后续步骤

Application is now:

✅ Fully modernized (latest dependencies)
✅ 100% spec coverage maintained
✅ Tests passing with high coverage
✅ Specs synchronized with implementation
✅ Ready for ongoing spec-driven development

---

应用现已：

✅ 完全实现现代化（使用最新依赖项）
✅ 保持100%的规范覆盖率
✅ 测试用例全部通过且覆盖率达标
✅ 规范与实现保持同步
✅ 可进行持续的规范驱动开发

---

Configuration in State File

状态文件配置

The modernize flag is set during Gear 1:

json

{
  "path": "brownfield",
  "modernize": true,
  "metadata": {
    "modernizeRequested": "2024-11-17T12:00:00Z",
    "upgradeScope": "all-dependencies",
    "targetCoverage": 85
  }
}

modernize标志在Gear 1阶段设置：

json

{
  "path": "brownfield",
  "modernize": true,
  "metadata": {
    "modernizeRequested": "2024-11-17T12:00:00Z",
    "upgradeScope": "all-dependencies",
    "targetCoverage": 85
  }
}

When Modernize Runs

现代化改造的运行时机

In Cruise Control:

Automatically runs after Gear 6 if
```
modernize: true
```

In Manual Mode:

Skill becomes available after Gear 6 completes
User explicitly invokes:
```
/stackshift.modernize
```
or skill auto-activates

在巡航控制模式下：

若设置了
```
modernize: true
```
，则在Gear 6完成后自动运行

在手动模式下：

完成Gear 6后该技能可用
用户可显式调用：
```
/stackshift.modernize
```
，或技能自动激活

Success Criteria

成功标准

Modernization complete when:

✅ All dependencies updated to latest stable versions
✅ All tests passing
✅ Test coverage ≥ 85% on all modules
✅ Build successful (no compilation errors)
✅ /speckit.analyze shows no drift
✅ No high/critical security vulnerabilities
✅ Specs updated where behavior changed
✅ Upgrade report generated

现代化改造完成的标志：

✅ 所有依赖项已更新至最新稳定版本
✅ 所有测试用例通过
✅ 所有模块的测试覆盖率≥85%
✅ 构建成功（无编译错误）
✅ /speckit.analyze显示无偏差
✅ 无高/严重级安全漏洞
✅ 行为变更处已更新规范
✅ 已生成升级报告

Benefits of Brownfield Upgrade

遗留系统升级的优势

vs. Standard Brownfield:

对比标准遗留系统流程：

✅ Modern dependencies (not stuck on old versions)
✅ Security updates (latest patches)
✅ Performance improvements (newer libraries often faster)
✅ New features (latest library capabilities)
✅ Reduced technical debt (no old dependencies)

✅ 现代化依赖项（不再受困于旧版本）
✅ 安全更新（最新补丁）
✅ 性能提升（新版本库通常更快）
✅ 新功能（最新库的功能）
✅ 减少技术债务（无旧依赖项）

vs. Greenfield:

对比全新系统（Greenfield）开发：

✅ Faster (upgrade vs. rebuild)
✅ Lower risk (incremental changes vs. rewrite)
✅ Spec-guided (specs help fix breaking changes)
✅ Keeps working code (only changes dependencies)

✅ 更快速（升级 vs 重建）
✅ 风险更低（增量变更 vs 重写）
✅ 规范驱动（规范指导修复破坏性变更）
✅ 保留可用代码（仅变更依赖项）

Use Case:

适用场景：

Perfect for teams that want to modernize without full rewrites. Get the benefits of modern tooling while maintaining existing features.

非常适合希望在不进行完全重写的前提下实现现代化的团队。在保留现有功能的同时，获得现代化工具链的优势。

Technical Approach

技术方案

Spec-Driven Upgrade Strategy

规范驱动的升级策略

Specs as Safety Net:
- Every feature has acceptance criteria
- Run tests against specs after each upgrade
- If tests fail, specs guide the fix
Incremental Upgrades:
- Upgrade in phases (minor first, then majors)
- Run tests after each phase
- Rollback if too many failures
Coverage as Quality Gate:
- Must maintain 85%+ throughout upgrade
- Add tests for new library behaviors
- Ensure edge cases covered
Spec Synchronization:
- If library changes behavior, update spec
- If implementation changes, update spec
- /speckit.analyze validates alignment

Result: A fully modernized application under complete spec-driven control!

规范作为安全网：
- 每个功能都有验收标准
- 每次升级后针对规范运行测试
- 若测试失败，规范指导修复方向
增量式升级：
- 分阶段升级（先小版本，再大版本）
- 每个阶段后运行测试
- 若失败过多则回滚
覆盖率作为质量门控：
- 升级全程需保持85%以上的覆盖率
- 为新库的行为添加测试用例
- 确保覆盖边缘场景
规范同步：
- 若库变更了行为，更新规范
- 若实现方式变更，更新规范
- /speckit.analyze验证一致性

最终结果：一个完全现代化且处于规范驱动全面控制下的应用！