code-necromancer

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Code Necromancer

Tagline: Raise dead codebases from the grave

Systematic framework for understanding, resurrecting, and modernizing legacy codebases.

标语: 从“坟墓”中唤醒遗留代码库

一套用于理解、复活并现代化遗留代码库的系统性框架。

When to Activate

适用场景

✅ Use when:

Inheriting a codebase with 5+ repos and no documentation
Resurrecting a product dormant for 2+ years
Joining a company with significant technical debt and tribal knowledge loss
Performing due diligence on acquired codebases
Modernizing legacy systems without breaking existing functionality

❌ NOT for:

Greenfield projects (start fresh instead)
Well-documented active codebases
Simple bug fixes in maintained systems

✅ 推荐使用场景:

接手包含5个以上repo且无文档的代码库
复活已停滞2年以上的产品
加入存在大量技术债务且核心知识流失的公司
对收购的代码库进行尽职调查
在不破坏现有功能的前提下现代化遗留系统

❌ 不适用场景:

新项目（建议从零开始）
文档完善的活跃代码库
维护中系统的简单Bug修复

The Three Phases

三个核心阶段

Phase 1: ARCHAEOLOGY

第一阶段：ARCHAEOLOGY（考古）

Objective: Create a complete map before touching anything.

Output	Description
`repo-inventory.json`	All repos with metadata, languages, activity
`dependency-graph.mmd`	Inter-repo and external dependencies
`architecture-diagram.mmd`	Visual system topology
`tech-stack-matrix.md`	Language/framework versions per repo
`maturity-assessment.md`	Code quality, test coverage, docs quality
`missing-pieces.md`	Gaps, orphaned repos, broken integrations

Process: Inventory → Deep Scan → Cross-Reference → Visualize → Assess

→ See

references/archaeology-guide.md

for detailed techniques.

目标: 在修改代码前，先完成完整的代码库映射。

输出物	描述
`repo-inventory.json`	包含所有repo及其元数据、开发语言、活跃度的清单
`dependency-graph.mmd`	repo间及外部依赖关系图
`architecture-diagram.mmd`	可视化系统拓扑图
`tech-stack-matrix.md`	各repo对应的语言/框架版本矩阵
`maturity-assessment.md`	代码质量、测试覆盖率、文档质量评估报告
`missing-pieces.md`	存在的缺口、孤立repo、失效集成的记录

流程: 清单梳理 → 深度扫描 → 交叉验证 → 可视化呈现 → 成熟度评估

→ 详见

references/archaeology-guide.md

获取详细技术指南。

Phase 2: RESURRECTION

第二阶段：RESURRECTION（复活）

Objective: Get the system running in development.

Output	Description
`dependency-audit.md`	Outdated packages, vulnerabilities, breaking changes
`environment-variables.md`	All required env vars with defaults
`secrets-needed.md`	API keys, certs, OAuth credentials
`infrastructure-status.md`	Cloud resources, what exists vs deleted
`resurrection-blockers.md`	Critical issues preventing launch
`integration-tests/`	Tests verifying components work and communicate

Process: Audit Dependencies → Map Environment → Check Infrastructure → Write Tests → Document Blockers

→ See

references/integration-test-patterns.md

for resurrection test patterns.

目标: 让系统能在开发环境中正常运行。

输出物	描述
`dependency-audit.md`	过时包、漏洞、破坏性变更的审计报告
`environment-variables.md`	所有必要环境变量及默认值清单
`secrets-needed.md`	API密钥、证书、OAuth凭证等敏感信息清单
`infrastructure-status.md`	云资源现状记录（已存在/已删除）
`resurrection-blockers.md`	阻碍系统启动的关键问题清单
`integration-tests/`	验证组件正常运行及通信的集成测试用例

流程: 依赖审计 → 环境映射 → 基础设施检查 → 编写测试 → 记录阻碍因素

→ 详见

references/integration-test-patterns.md

获取复活阶段测试模式。

Phase 3: REJUVENATION

第三阶段：REJUVENATION（复兴）

Objective: Modernize while maintaining feature parity.

Output	Description
`security-recommendations.md`	Vulnerability fixes, compliance
`modernization-roadmap.md`	Prioritized upgrades with effort estimates
`architecture-improvements.md`	Scalability, performance, maintainability

Process: Security First → Infrastructure (containerize, CI/CD) → Code Quality → Architecture

目标: 在保持功能一致性的前提下实现代码现代化。

输出物	描述
`security-recommendations.md`	漏洞修复、合规性相关建议
`modernization-roadmap.md`	带有工作量估算的优先级升级路线图
`architecture-improvements.md`	关于可扩展性、性能、可维护性的架构优化建议

流程: 安全优先 → 基础设施优化（容器化、CI/CD）→ 代码质量提升 → 架构重构

Key Commands

关键命令

bash

undefined

bash

undefined

List all repos in org

列出组织内所有repo

gh repo list ORG --limit 1000 --json name,primaryLanguage,pushedAt

Dependency analysis

依赖分析

npm audit && npm outdated # Node.js pip list --outdated && safety check # Python go mod graph # Go

Find env vars in code

在代码中查找环境变量

grep -rn 'process.env|os.environ' --include=".js" --include=".py"


→ See `references/framework-detection.md` for framework/stack identification.
→ See `references/infrastructure-mapping.md` for cloud resource discovery.
→ See `references/dependency-patterns.md` for dependency detection.

grep -rn 'process.env|os.environ' --include=".js" --include=".py"


→ 详见 `references/framework-detection.md` 获取框架/技术栈识别方法。
→ 详见 `references/infrastructure-mapping.md` 获取云资源发现指南。
→ 详见 `references/dependency-patterns.md` 获取依赖检测方法。

Anti-Patterns to Avoid

需规避的反模式

1. Premature Resurrection

1. 过早复活

What it looks like: Running

npm install

before reading any code Why it's wrong: You'll fix the same bug 5 times; dependencies have changed Fix: Complete archaeology first; understand before touching

表现: 还没阅读任何代码就运行

npm install

危害: 会重复修复同一个Bug；依赖关系已发生变化 解决方法: 先完成考古阶段；先理解再动手

2. Scope Creep

2. 范围蔓延

What it looks like: "Let's also refactor while we're here" Why it's wrong: Scope explosion; never actually resurrect Fix: Strict phase separation; refactoring is Phase 3

表现: “既然我们在这里，顺便重构一下吧” 危害: 范围失控；永远无法完成复活 解决方法: 严格区分各阶段；重构属于第三阶段

3. Big Bang Updates

3. 一次性大更新

What it looks like: Update all dependencies in one commit Why it's wrong: Something breaks, no idea what Fix: Update incrementally; test after each

表现: 一次提交就更新所有依赖危害: 出现问题后无法定位根源 解决方法: 增量更新；每次更新后都进行测试

4. Ignoring Tests

4. 忽略测试

What it looks like: "It runs, ship it" Why it's wrong: Regression city; no baseline for changes Fix: Write resurrection tests as you go; they prove progress

表现: “能运行就行，上线吧” 危害: 回归问题频发；没有变更基准 解决方法: 边复活边编写测试；测试是进度的证明

5. Undocumented Changes

5. 无文档变更

What it looks like: "I fixed it but forgot what I changed" Why it's wrong: Tribal knowledge returns; next person is you in 6 months Fix: Document everything you learn and change

表现: “我修复了问题，但忘了改了什么” 危害: 核心知识再次流失；6个月后的你会重蹈覆辙 解决方法: 记录所有学到的信息及做出的变更

6. Trusting Old Documentation

6. 轻信旧文档

What it looks like: Following README from 2019 Why it's wrong: APIs change, services get deprecated Fix: Verify every instruction; documentation lies

表现: 遵循2019年的README操作危害: API已变更、服务已废弃 解决方法: 验证每一条指令；文档可能过时

Success Metrics

成功指标

Archaeology Complete When:

考古阶段完成标志:

Resurrection Complete When:

复活阶段完成标志:

All services start locally
Services can communicate with each other
Integration tests pass
At least one full user flow works

所有服务可在本地启动
服务间可正常通信
集成测试全部通过
至少一个完整用户流程可正常运行

Rejuvenation Complete When:

复兴阶段完成标志:

References

参考资料

→

references/archaeology-guide.md

- Deep code archaeology techniques →

references/dependency-patterns.md

- Dependency detection across ecosystems →

references/framework-detection.md

- Framework/stack identification →

references/infrastructure-mapping.md

- Cloud resource discovery →

references/integration-test-patterns.md

- Resurrection test patterns

→

references/archaeology-guide.md

- 深度代码考古技术指南 →

references/dependency-patterns.md

- 跨生态系统依赖检测方法 →

references/framework-detection.md

- 框架/技术栈识别指南 →

references/infrastructure-mapping.md

- 云资源发现指南 →

references/integration-test-patterns.md

- 复活阶段测试模式

Templates

模板

→

templates/repo-inventory.json

- Repository catalog →

templates/archaeology-report.md

- Phase 1 output →

templates/resurrection-plan.md

- Phase 2 output →

templates/rejuvenation-roadmap.md

- Phase 3 output

→

templates/repo-inventory.json

- 代码库编目模板 →

templates/archaeology-report.md

- 第一阶段输出报告模板 →

templates/resurrection-plan.md

- 第二阶段计划模板 →

templates/rejuvenation-roadmap.md

- 第三阶段路线图模板