1. 接手老项目时，为什么第一步永远是摸清技术栈

接手一个老项目，最怕的不是代码写得烂，而是你根本不知道它烂在哪。我见过太多同行，拿到一个维护了三五年的项目，上来就改需求、加功能，结果改到一半发现底层框架版本对不上、依赖包互相打架、构建脚本里藏着七八个历史遗留的硬编码路径。这种时候，你花在“救火”上的时间，远比一开始花半天摸清技术栈要多得多。

“只管去写”这个系列我一直在跟，day2 这个主题选得特别实在——用 Claude 来分析老项目的技术栈。这件事的核心价值在于：把原本需要一整天甚至更久的“考古式阅读”，压缩到几十分钟的结构化梳理。你不需要逐行读代码，而是让模型帮你从配置文件、目录结构、依赖清单里提取关键信息，快速画出一张技术栈全景图。

这篇文章适合谁看？三类人最受益：第一类是刚接手遗留项目的开发者，需要快速建立认知地图；第二类是技术负责人，要在重构前做技术债务评估；第三类是对 AI 辅助代码分析感兴趣、想找一套可复现流程的工程师。不管你用的是哪种语言、哪种框架，这套方法都能直接抄作业。

我先说结论：分析老项目技术栈，核心不是“让 AI 读代码”，而是“给 AI 喂对上下文”。喂错了，它给你的就是一堆正确的废话；喂对了，它能帮你省掉大量翻文件的时间。下面我把整个思路、操作细节、踩过的坑，完整拆一遍。

2. 整体分析思路：从“文件考古”到“结构化输出”

2.1 老项目技术栈分析到底要分析什么

很多人一提到“分析技术栈”，脑子里第一反应就是“用了什么框架”。这太窄了。一个老项目的技术栈至少包含六个维度，缺一个都可能导致你后续判断失误。

第一个维度是语言与运行时版本。比如项目用的是哪个大版本的编程语言，运行时环境有没有锁死版本，这些信息通常藏在版本管理文件或容器配置里。第二个维度是核心框架与库。这是大家最关注的，但要注意区分“直接依赖”和“间接依赖”，老项目里间接依赖往往是坑最多的地方。第三个维度是构建与打包工具链。老项目经常出现构建工具版本和框架版本不匹配的情况，比如框架升级了但构建配置没跟着改。第四个维度是数据存储与中间件。数据库类型、缓存方案、消息队列，这些决定了项目的部署形态和扩展能力。第五个维度是测试与质量保障体系。有没有单元测试、集成测试，用的是哪套测试框架，这直接反映项目的可维护性。第六个维度是部署与运维方式。是容器化部署还是传统部署，有没有持续集成配置，这些影响你后续的发布流程。

把这六个维度列清楚之后，你会发现：分析技术栈的本质，是还原这个项目的“技术决策历史”。每一个依赖、每一个配置，背后都是当时某个人的选择。Claude 的价值在于，它能帮你把这些散落在各处的线索快速聚合起来。

2.2 为什么选 Claude 而不是自己翻文件

自己翻文件当然可以，但效率差距很大。我做过对比：一个中等规模的老项目，大概两百多个源文件、十几个配置文件，人工梳理一遍技术栈，认真做的话需要三到四个小时。用 Claude 辅助，把关键文件喂进去，二十分钟左右就能拿到一份结构化的分析报告，剩下的时间用来验证和补充。

Claude 在这件事上有三个明显优势。第一是长上下文能力，你可以一次性把多个配置文件、目录树、依赖清单塞进去，它能跨文件关联信息。第二是结构化归纳能力，你让它按维度输出，它不会漏掉你指定的分类。第三是解释能力，它不只是告诉你“用了什么”，还能解释“这个配置可能意味着什么”，这对判断技术债务很有帮助。

但要注意，Claude 不是万能的。它看不到你的运行时环境，也读不到那些没有写进文件的隐性约定。所以我的做法是：Claude 负责“提取和归纳”，我负责“验证和判断”。这个分工一定要清晰，否则你会被它的错误推断带偏。

2.3 分析流程的四个阶段

整个流程我拆成四个阶段，每个阶段都有明确的输入和输出。

第一阶段是信息采集。把项目里所有能反映技术栈的文件找出来，包括依赖清单、构建配置、容器配置、目录结构说明、环境变量示例等。这个阶段的关键是“宁多勿漏”，先把材料备齐。

第二阶段是结构化投喂。把采集到的文件按类别整理好，分批喂给 Claude，每一批都给出明确的指令，告诉它要提取什么、按什么格式输出。这个阶段的关键是“指令要具体”，模糊的指令只会得到模糊的结果。

第三阶段是交叉验证。拿到 Claude 的输出后，对照实际项目逐项核实。重点核实版本号、依赖关系、配置项的实际作用。这个阶段的关键是“不盲信”，模型说的每一句话都要有文件依据。

第四阶段是补充与归档。把验证后的结果整理成一份技术栈文档，标注清楚哪些是确认的、哪些是存疑的、哪些需要进一步排查。这份文档就是你后续所有工作的基础。

提示：整个流程里，第二阶段和第三阶段是最容易出问题的。投喂时指令不清晰，验证时不够仔细，都会导致最终结论不可靠。

3. 核心细节解析：喂什么、怎么喂、注意什么

3.1 必须采集的关键文件清单

老项目里，能反映技术栈的文件其实就那么几类，但很多人会漏掉一些关键项。我整理了一份清单，按优先级排序。

最高优先级的是依赖管理文件。不同语言有不同的叫法，比如包管理器的锁文件、依赖声明文件、版本约束文件。这类文件直接告诉你项目用了哪些库、什么版本。锁文件尤其重要，因为它记录的是实际安装的版本，而不是声明允许的版本范围。

次高优先级的是构建与容器配置文件。构建脚本能反映编译目标、打包方式、环境变量注入方式；容器配置能反映基础镜像、运行时环境、暴露端口。这两类文件结合起来，基本能还原项目的运行形态。

第三优先级的是目录结构与入口文件。目录结构能反映项目的架构模式，比如是分层架构还是模块化架构；入口文件能反映启动流程和核心依赖注入方式。

第四优先级的是环境配置示例与文档。环境变量示例文件能反映项目依赖哪些外部服务；项目文档能反映当时的部署要求和已知问题。

下面这张表可以帮你快速对照检查：

采集的时候有个小技巧：先用目录树命令把整体结构导出来，再针对性地找文件。不要一上来就逐个打开文件看，那样效率太低。先看结构，再定位关键文件，最后批量读取内容。

3.2 给 Claude 的指令应该怎么写

指令写得好不好，直接决定输出质量。我试过很多种写法，最后总结出一个模板，效果比较稳定。

指令要包含四个要素：角色设定、任务描述、输出格式、约束条件。角色设定是告诉它“你是一个资深架构师，正在做技术栈审计”；任务描述是告诉它“从以下文件中提取技术栈信息”；输出格式是告诉它“按语言运行时、框架库、构建工具、数据存储、测试体系、部署方式六个维度输出”；约束条件是告诉它“不确定的信息标注为待确认，不要编造版本号”。

我举个例子，实际用的指令大概长这样：

你是一名资深后端架构师，正在对一个遗留项目做技术栈审计。 以下是我提供的项目文件内容，请从中提取技术栈信息。 要求： 1. 按六个维度输出：语言与运行时、核心框架与库、构建与打包、数据存储与中间件、测试与质量、部署与运维。 2. 每个维度列出具体名称和版本号，版本号必须来自文件原文。 3. 如果某个信息在文件中找不到，标注“未在提供文件中体现”，不要推测。 4. 对于存在版本冲突或配置矛盾的项，单独列出并说明依据。 5. 输出用 Markdown 表格，方便我后续整理。 以下是文件内容： [粘贴文件内容]

这个模板的关键在于约束条件足够严格。尤其是“不要推测”和“标注未体现”这两条，能大幅减少模型编造信息的概率。我早期没加这两条的时候，Claude 经常给我一些看起来合理但实际不存在的版本号，后来加上之后，输出可靠多了。

还有一个细节：分批投喂比一次性投喂效果好。如果你把几十个文件一次性塞进去，模型可能会忽略掉一些细节。我的做法是按类别分三到四批，每批投喂后先检查输出，再投下一批。这样虽然多花几分钟，但准确率明显提升。

3.3 分析结果里最容易出错的三个地方

即使指令写得很清楚，Claude 的输出里还是有三类错误最常见，你必须重点核查。

第一类是版本号误读。老项目的依赖文件里经常有版本范围符号，比如“大于等于某版本”、“兼容某版本”，模型有时候会把范围符号当成精确版本。核查方法是直接打开锁文件对照，锁文件里的版本才是实际安装的版本。

第二类是依赖关系误判。模型看到某个库被引入，就认为它是核心依赖，但实际上它可能只是某个间接依赖的传递依赖。核查方法是看依赖声明文件里有没有直接声明，没有直接声明的就是间接依赖。

第三类是配置项作用误读。构建配置里的某些参数，模型可能会按字面意思解释，但实际上在老项目里有特殊的历史含义。核查方法是结合项目文档和提交记录来判断，如果文档缺失，就在分析结果里标注“需人工确认”。

注意：这三类错误里，版本号误读的危害最大。因为版本号直接决定你后续能不能顺利安装依赖、能不能复现构建。我踩过一次坑，模型把一个测试库的版本读错了，导致我按错误版本去安装，折腾了半天才发现问题。

4. 实操过程：从零开始分析一个老项目

4.1 第一步：导出项目结构并做初步筛选

拿到项目之后，先别急着打开代码文件。第一步是导出目录结构，对项目规模有个整体认知。

如果你用的是常见的版本控制工具，可以直接用命令行导出目录树。我通常用这样的命令：

# 导出目录结构，排除依赖包目录和构建产物目录 find . -type d \( -name "依赖包目录名" -o -name "构建产物目录名" -o -name "版本控制目录名" \) -prune -o -type f -print | head -200

这个命令的作用是列出项目里的文件，但排除掉那些体积大、信息密度低的目录。为什么要排除？因为依赖包目录里动辄几万个文件，全导出来既慢又没用，你需要的是项目自身的文件结构。

导出之后，先扫一眼顶层目录。重点关注这几类目录：源码目录、配置文件目录、脚本目录、文档目录。如果看到一些命名很奇怪的目录，比如“临时”、“备份”、“旧版”之类的，先记下来，这些往往是历史遗留的重灾区。

初步筛选的目标是确定哪些文件需要喂给 Claude。我的标准是：依赖清单、构建配置、容器配置、环境示例这四类必喂；源码目录只喂入口文件和核心模块的索引文件；文档目录挑最新的读。

4.2 第二步：分批投喂与结构化提取

筛选完文件之后，进入投喂阶段。我一般分三批。

第一批投喂依赖清单和版本约束文件。这一批的目标是提取完整的依赖列表和版本信息。指令里明确要求输出“直接依赖”和“间接依赖”两个列表，并标注版本来源。

第二批投喂构建配置和容器配置。这一批的目标是提取构建流程和运行环境信息。指令里要求输出“构建步骤”、“环境变量”、“运行时依赖”三个部分。

第三批投喂目录结构和入口文件。这一批的目标是提取架构模式和模块划分。指令里要求输出“模块列表”、“模块职责”、“模块间依赖关系”。

每批投喂之后，我都会让 Claude 先输出一个简短的摘要，确认它理解了我的指令，再让它输出完整结果。这个“先摘要后详情”的做法，能提前发现指令理解偏差，避免白跑一遍。

投喂过程中有个细节要注意：文件内容要保留原始格式。不要为了省字数把配置文件压缩成一行，那样模型可能会丢失缩进和层级信息。尤其是容器配置和构建配置，缩进本身就是语法的一部分。

4.3 第三步：交叉验证与人工复核

拿到三批输出之后，进入验证阶段。这一步不能省，而且要认真做。

验证的方法是逐项对照。打开原始文件，对照 Claude 的输出，一项一项核对。重点核对版本号、依赖关系、配置项名称。核对过程中，我会用不同颜色的标记区分三类结果：确认无误的、有疑问的、错误的。

有疑问的项，我会进一步查证。查证的方式包括：搜索项目提交记录、查看相关文档、在测试环境实际运行验证。错误的项，直接修正并记录错误原因，方便后续优化指令。

这个阶段最耗时间，但也是最关键的。我一般会花整个分析流程一半的时间在验证上。因为未经验证的分析结果，比没有分析结果更危险——它会给你一种“我已经了解了”的错觉，但实际上可能是错的。

4.4 第四步：整理成可复用的技术栈文档

验证完成后，把结果整理成一份文档。这份文档的结构我建议包含五个部分：技术栈概览、依赖清单、构建与部署说明、已知问题与风险、待确认事项。

技术栈概览用表格呈现，一页纸能看完最好。依赖清单按直接依赖和间接依赖分开列，标注版本和用途。构建与部署说明写清楚从代码到运行的完整流程。已知问题与风险列出分析过程中发现的矛盾点和潜在隐患。待确认事项列出那些文件里没写清楚、需要进一步排查的点。

这份文档的价值在于：它是你后续所有工作的基础。改需求、修缺陷、做重构，都要先看这份文档。而且它可以直接传给下一个接手的人，省掉重复分析的成本。

5. 常见问题与排查技巧实录

5.1 模型输出与实际情况不符怎么办

这是最常见的问题。模型说用了某个版本，实际一查不是；模型说某个配置项是某个作用，实际是另一个作用。遇到这种情况，先别急着否定模型，按下面的顺序排查。

首先检查投喂的文件内容是否完整。有时候文件内容被截断了，模型只能根据残缺信息推断。其次检查指令是否足够明确。如果指令里没有要求“标注来源”，模型可能会把不同文件的信息混在一起。最后检查是否存在同名不同版本的文件。老项目里经常有多个配置文件，分别对应不同环境，模型可能读混了。

排查完之后，如果确认是模型的问题，就把错误案例记下来，用来优化下一次的指令。我自己的经验是：同一个错误出现两次以上，就说明指令需要调整了。

5.2 项目文件太多，上下文放不下怎么办

这是很现实的问题。老项目动辄几百个文件，不可能全部塞进去。我的处理策略是分层筛选。

第一层是必读文件，就是前面说的依赖清单、构建配置、容器配置、环境示例，这些文件数量少、信息密度高，必须完整投喂。第二层是选读文件，包括入口文件、核心模块索引、最新文档，这些文件挑重点投喂。第三层是参考文件，包括测试文件、脚本文件、历史文档，这些文件只在需要时投喂。

如果必读文件加起来还是超长，就用摘要投喂的方式。先把文件内容做一次摘要，只保留关键信息，再投喂给模型。摘要的时候要注意保留版本号、配置项名称、依赖关系这些硬信息，去掉注释和空行。

5.3 分析结果里出现矛盾信息怎么处理

矛盾信息通常有三种来源。第一种是文件本身就有矛盾，比如依赖声明文件和锁文件版本不一致。这种情况说明项目在某个时间点做过手动修改，需要以锁文件为准，同时记录这个矛盾点。第二种是模型理解偏差，把不同文件的信息错误关联。这种情况需要重新投喂，把相关文件分开处理。第三种是历史遗留，项目里同时存在新旧两套配置，模型把两套混在一起了。这种情况需要先确认哪套是当前生效的，再针对性分析。

处理矛盾信息的原则是：以实际运行结果为准，以锁文件为准，以最新提交为准。三个“为准”按优先级排序，能解决大部分矛盾。

5.4 常见问题速查表

5.5 几个我踩过的坑和对应的技巧

第一个坑是过度依赖模型输出。我早期做分析的时候，模型说什么我就信什么，结果在一个项目的部署配置上栽了跟头。模型说某个端口是服务端口，实际是管理端口，导致我部署时配错了。后来我养成了一个习惯：凡是涉及端口、路径、版本号的信息，必须打开原文件亲眼确认。

第二个坑是忽略间接依赖。老项目的间接依赖往往是安全漏洞和版本冲突的重灾区。我现在的做法是，让模型单独输出一份间接依赖清单，然后重点检查那些版本明显偏旧的项。

第三个坑是没有记录分析过程。第一次分析完，过了一个月再回头看，完全不记得当时为什么得出某个结论。后来我开始在分析文档里加一列“判断依据”，写清楚每个结论是从哪个文件、哪一行得出的。这个习惯帮我省了很多重复排查的时间。

第四个坑是一次性投喂太多文件。模型处理长上下文时，对中间部分的注意力会下降。我现在的做法是每批不超过五个文件，每个文件不超过两千行。超过的部分先做摘要。

提示：如果你用的是支持文件上传的分析工具，注意文件格式。纯文本格式的解析效果最好，富文本格式可能会丢失格式信息。

6. 分析完之后，这份技术栈报告怎么用

拿到技术栈报告之后，它的用途远不止“了解一下”。我通常会在四个场景里用到它。

第一个场景是制定改造计划。报告里列出的旧版本依赖、矛盾配置、缺失测试，都是改造的切入点。你可以按风险高低排序，先处理影响面大的问题。比如某个核心库的版本已经停止维护了，那就要优先安排升级。

第二个场景是评估工作量。技术栈报告能帮你快速判断一个需求的实现成本。如果需求涉及的模块用的是老旧框架，那工作量就要往上调；如果涉及的是相对独立的模块，那风险就小很多。

第三个场景是新人上手。把技术栈报告作为新人入职的第一份阅读材料，能大幅缩短他们的熟悉周期。报告里写清楚了项目用了什么、怎么构建、怎么部署，新人按图索骥就行。

第四个场景是技术债务追踪。报告里标注的“待确认事项”和“已知风险”，可以作为技术债务清单的初始版本。每次迭代时回顾一下，看看有没有可以顺手解决的。

我个人在实际操作中的体会是：技术栈分析不是一次性的工作，而是持续的过程。项目在演进，技术栈也在变化。建议每隔一个季度或者每次大版本发布后，重新跑一遍分析流程，更新技术栈报告。这样你手里始终有一份最新的项目认知地图，不管是做决策还是交接，都有据可依。

最后再分享一个小技巧：分析的时候，让 Claude 顺便输出一份“技术栈变更建议”。它会根据当前版本和常见实践，给出一些升级或替换的建议。这些建议不一定都对，但可以作为你后续技术调研的起点，省掉一些从零开始查资料的时间。