Fondamenta ArchCode 完全教程：零依赖的代码分析神器，让AI真正理解你的项目

📝 教程简介

你是否遇到过这样的困扰：AI助手帮你修改BUG，改好一个却又出现新的？根本原因是AI只看到了局部代码，没有理解全局依赖。

今天介绍的 Fondamenta ArchCode，是一个超轻量的代码分析工具，它能在几秒内分析你的整个项目，生成结构化的Markdown文档，让任何AI都能真正理解你的代码结构。

它的最大优势：

• ✅ 零依赖 - 不需要数据库，不需要运行服务器
• ✅ 超快速 - 1000+文件的项目只需3秒
• ✅ 框架感知 - 能识别Next.js的页面、组件、API路由、认证模式
• ✅ 任何AI都能用 - 生成的是Markdown文件，Claude、ChatGPT、Cursor、Copilot都能直接读取
• ✅ 支持全局安装 - 一次安装，到处使用

📚 目录

1. 什么是Fondamenta ArchCode？
2. 安装前的准备
3. 全局安装教程（超详细）
4. 基础使用：分析你的项目
5. 理解生成的文档
6. 高级命令详解
7. 在AI工具中配合使用
8. 与其他工具对比
9. 实战示例
10. 常见问题解决
11. 总结与建议

1. 什么是Fondamenta ArchCode？

Fondamenta ArchCode 是一个专为AI辅助编程设计的静态代码分析工具。它扫描你的代码库，生成结构化的Markdown文件，让AI能够“读懂”你的项目架构。

它解决了什么问题？

传统的AI工具（如Cursor、Copilot、Claude Code）虽然强大，但它们缺乏对代码库整体结构的理解。它们看到的是一个个独立的文件，却不知道：

• 哪些组件依赖什么模块
• API路由如何连接到数据库模型
• 每个页面使用了什么认证模式

Fondamenta ArchCode 通过生成以下文档，完美解决这个问题：

• 依赖关系图 - 组件之间的调用关系
• 页面分析 - 每个页面的导入、认证、数据获取
• API路由文档 - 每个接口的方法、认证、关联模型
• 数据库模型 - 模型字段、关系、枚举
• 组件图谱 - 可视化的依赖树

2. 安装前的准备

2.1 检查Node.js是否安装

Fondamenta ArchCode 基于Node.js运行，需要先安装Node.js环境。

检查方法：

# 打开PowerShell（Win + R，输入powershell，回车）
node --version

预期输出：

v18.0.0 或更高版本

如果显示“无法识别”或类似信息，说明没有安装Node.js。

安装Node.js：

1. 访问 nodejs.org
2. 下载LTS版本（推荐）
3. 双击安装，一路“下一步”即可
4. 安装完成后重启PowerShell，再次运行node --version验证

2.2 确认你的项目路径

找到你想要分析的项目根目录，例如：

• Z:\www\wwwroot\ws.wnmax.com
• D:\我的项目\商城项目
• C:\Users\用户名\source\repos\myapp

记住这个路径，后续所有操作都需要先进入这个目录。

3. 全局安装教程（超详细）

Fondamenta ArchCode 支持两种使用方式：npx临时使用 和 全局安装。本教程推荐全局安装，因为：

3.1 以管理员身份打开PowerShell

为什么需要管理员权限？
全局安装需要写入系统目录（如C:\Program Files\nodejs），需要管理员权限。

操作步骤：

1. 按 Win + X，选择 “Windows PowerShell(管理员)” 或 “终端(管理员)”
2. 如果弹出用户账户控制提示，点击 “是”

3.2 执行全局安装命令

在管理员PowerShell中，输入以下命令：

npm install -g fondamenta-archcode

安装过程详解：

步骤1：npm开始下载

npm notice 
npm notice New minor version of npm available! 10.8.2 -> 10.9.2
npm notice Changelog: https://github.com/npm/cli/releases/tag/v10.9.2
npm notice To update run: npm install -g npm@10.9.2
npm notice 

步骤2：下载并安装包

added 89 packages in 3s

步骤3：安装完成

+ fondamenta-archcode@0.0.7
installed 1 package in 3.212s

3.3 验证全局安装是否成功

# 查看全局安装列表
npm list -g --depth=0

成功标志：输出中包含 fondamenta-archcode@0.0.7

# 直接运行命令验证
fondamenta --version
# 或
fondamenta -h

如果显示帮助信息，说明安装成功！

3.4 可能遇到的安装问题及解决

问题1：权限错误

Error: EACCES: permission denied

解决：确保以管理员身份运行PowerShell

问题2：网络超时

Error: connect ETIMEDOUT

解决：切换npm镜像源

# 使用淘宝镜像
npm config set registry https://registry.npmmirror.com
# 重新安装
npm install -g fondamenta-archcode

问题3：文件占用

Error: EBUSY: resource busy or locked

解决：关闭所有编辑器、文件资源管理器窗口，重启PowerShell再试

4. 基础使用：分析你的项目

4.1 进入项目目录

cd Z:\www\wwwroot\ws.wnmax.com

（替换为你的实际项目路径）

4.2 运行分析命令

fondamenta analyze

执行过程详解：

步骤1：工具开始扫描

🔍 Analyzing codebase...

步骤2：显示分析进度

📁 Scanning files... (324 files found)
🔎 Parsing TypeScript files...
📊 Building dependency graph...
📝 Generating documentation...

步骤3：分析完成

✅ Analysis complete! Generated files in: Z:\www\wwwroot\ws.wnmax.com\.planning
📊 Found 324 files, 156 components, 89 API routes
⏱️  Total time: 2.8 seconds

4.3 查看生成的文档

# 进入 planning 目录
cd .planning

# 查看生成了哪些文件
dir
# 或
ls
# 或
Get-ChildItem

你会看到类似这样的文件列表：

目录: Z:\www\wwwroot\ws.wnmax.com\.planning

Mode                 LastWriteTime         Length Name
----                 -------------         ------ ----
-a----         2026/3/11     14:23          12458 DEPENDENCY-MAP.md
-a----         2026/3/11     14:23          35678 dependencies/

dependencies目录下包含详细的原子文档：

• pages-atomic.md - 所有页面的详细分析
• components-atomic.md - 所有组件的详细分析
• api-routes-atomic.md - 所有API路由的详细分析
• lib-atomic.md - 工具函数分析
• schema-crossref-atomic.md - 数据库模型分析
• component-graph.md - 组件依赖关系图

4.4 理解分析结果

以Next.js项目为例，生成的文档会包含：

pages-atomic.md 示例：

### `/dashboard`

- **File:** `app/(dashboard)/dashboard/page.tsx`
- **Type:** Server Component
- **Auth:** auth()
- **Data Fetching:**
  - DB: findMany (courses)
  - DB: count (flashcards)
- **Components:** CourseCard, StatsWidget, RecentActivity

api-routes-atomic.md 示例：

### `GET /api/users`

- **File:** `app/api/users/route.ts`
- **Auth:** requireAdmin()
- **Models:** User, Profile
- **Returns:** User[]
- **Error codes:** 401, 403, 500

5. 理解生成的文档

5.1 文档结构概览

.planning/
├── DEPENDENCY-MAP.md              # 整体架构概览
└── dependencies/
    ├── pages-atomic.md             # 页面分析
    ├── components-atomic.md        # 组件分析
    ├── api-routes-atomic.md        # API路由分析
    ├── lib-atomic.md               # 工具函数分析
    ├── schema-crossref-atomic.md   # 数据库模型
    └── component-graph.md          # 组件依赖图

5.2 核心文档详解

DEPENDENCY-MAP.md（整体架构）

这个文件提供了项目的宏观视图：

• 核心模块划分
• 主要依赖关系
• 循环依赖警告
• 影响范围分析

pages-atomic.md（页面分析）

每个页面的详细信息：

• 文件路径和类型（Server/Client Component）
• 使用的认证方式
• 数据获取逻辑
• 依赖的组件

api-routes-atomic.md（API分析）

每个接口的完整文档：

• HTTP方法
• 认证要求
• 关联的数据库模型
• 返回值类型
• 错误码

schema-crossref-atomic.md（数据库）

Prisma模型的交叉引用：

• 所有模型及其字段
• 模型之间的关系
• 枚举类型定义
• 字段被哪些API使用

5.3 文档特点

为什么这些文档对AI特别友好？

1. 结构化格式 - 使用Markdown标题、列表、代码块，AI能轻松解析
2. 一致性强 - 每个文件使用相同的格式模板
3. 信息完整 - 包含所有必要的上下文，无需多次查询
4. 人类可读 - 开发者也看得懂，可以直接阅读

6. 高级命令详解

6.1 监控模式：自动更新文档

当代码频繁变动时，可以启动监控模式，文件变化时自动重新分析：

# 启动监控
fondamenta watch

# 指定监控的目录
fondamenta watch --src ./src

# 忽略某些目录
fondamenta watch --ignore "node_modules,dist,.next"

使用场景：

• 开发过程中保持文档实时更新
• 配合AI助手实时调试
• 团队协作时确保文档同步

退出监控：按 Ctrl + C

6.2 差异分析：查看哪些文件变了

检测自上次分析以来哪些文件发生了变化：

# 查看差异
fondamenta diff

# 用于CI/CD流水线，如果文档过期则退出码为1
fondamenta diff --ci

输出示例：

📊 Changes since last analysis:
  - Modified: src/components/UserCard.tsx
  - Added: src/hooks/useAuth.ts
  - Deleted: src/utils/oldHelper.ts
  - Affected: 3 components, 2 API routes

6.3 生成AI上下文文件

自动生成各个AI工具的上下文配置文件：

# 生成 Claude 的 CLAUDE.md
fondamenta ai-context --claude

# 生成 Cursor 的 .cursorrules
fondamenta ai-context --cursor

# 生成 GitHub Copilot 的 copilot-instructions.md
fondamenta ai-context --copilot

# 生成所有配置文件
fondamenta ai-context --all

这些文件包含了项目结构的关键信息，让AI助手一开始就了解你的代码库。

6.4 自定义分析选项

# 指定输出目录
fondamenta analyze --output ./docs/codebase

# 排除特定目录
fondamenta analyze --ignore "node_modules,dist,.git,__tests__"

# 只分析特定文件类型
fondamenta analyze --ext "js,jsx,ts,tsx"

# 生成详细报告
fondamenta analyze --verbose

# 强制重新分析所有文件（忽略缓存）
fondamenta analyze --force

6.5 组合命令示例

日常开发工作流可以组合使用：

# 早上开始工作前
fondamenta analyze

# 修改代码后，查看影响范围
fondamenta diff

# 提交代码前，更新AI上下文
fondamenta ai-context --all

7. 在AI工具中配合使用

7.1 在Cursor中使用

方式1：直接引用文件
在对话中：

请参考 .planning/DEPENDENCY-MAP.md，给我介绍一下这个项目的整体架构

方式2：结合代码分析

我正在修改 src/components/UserCard.tsx，根据 .planning/components-atomic.md，这个组件还被哪些页面使用？

方式3：利用生成的.cursorrules
如果你运行了 fondamenta ai-context --cursor，Cursor会自动加载项目上下文，无需额外操作。

7.2 在Claude（Claude Code或Claude.ai）中使用

在Claude.ai中：
直接上传 .planning 文件夹，或者复制文档内容：

这是项目的依赖关系图：
[paste DEPENDENCY-MAP.md content]

请帮我分析如果修改 UserService，会影响哪些模块？

在Claude Code中：

# 确保生成了 CLAUDE.md
fondamenta ai-context --claude

# 然后运行 Claude Code
claude

Claude会自动读取 CLAUDE.md 中的项目上下文。

7.3 在GitHub Copilot中使用

运行以下命令生成Copilot指令：

fondamenta ai-context --copilot

生成的 copilot-instructions.md 会被Copilot自动识别，提供更准确的代码建议。

7.4 在ChatGPT/其他AI中使用

直接把文档内容复制粘贴给AI：

我需要你帮我调试这个项目。首先，这是项目的依赖关系图：

[paste DEPENDENCY-MAP.md]

现在我遇到了一个问题：[描述问题]

7.5 实战工作流示例

场景1：接手新项目

# 1. 克隆项目后
git clone 项目地址
cd 项目名

# 2. 运行分析
fondamenta analyze

# 3. 生成AI上下文
fondamenta ai-context --all

# 4. 在Cursor中提问
"请根据 .planning 文件夹，告诉我这个项目的核心功能模块和数据流向"

场景2：调试复杂BUG

# 1. 确保文档最新
fondamenta analyze

# 2. 在Cursor中提问
"我在 src/auth/login.ts 发现一个登录失败的BUG。
请先看 .planning/dependency-map.md，告诉我：
1. login.ts 依赖哪些模块？
2. 相关的API路由是哪些？
3. 涉及哪些数据库模型？
然后我们一起分析代码"

场景3：代码重构前分析

# 1. 运行差异分析
fondamenta diff

# 2. 如果修改较多，更新文档
fondamenta analyze

# 3. 在Cursor中提问
"我打算重构用户模块，把 UserService 拆分成多个小服务。
根据 .planning/dependencies/component-graph.md：
1. UserService 目前被哪些组件直接使用？
2. 间接依赖有哪些？
3. 重构后需要更新哪些API路由？"

8. 与其他工具对比

8.1 与GitNexus对比

8.2 与Repomix对比

8.3 适用场景建议

9. 实战示例

示例1：Next.js电商项目分析

项目信息：

• 技术栈：Next.js 14 + Prisma + TailwindCSS
• 文件数：1200+
• 功能：用户认证、商品管理、购物车、订单

操作步骤：

# 1. 进入项目
cd D:\projects\ecommerce-app

# 2. 全局分析
fondamenta analyze

# 3. 查看结果
cd .planning
dir

生成的文档统计（参考真实测试数据）：

Pages analyzed: 116
Components mapped: 487
API routes documented: 291
DB models cross-referenced: 109
Total time: < 3 seconds

在Cursor中提问：

根据 .planning/pages-atomic.md，哪些页面使用了购物车功能？
我想修改购物车的实现，根据 .planning/api-routes-atomic.md，需要更新哪些API？

示例2：Node.js后端API项目分析

项目信息：

• 技术栈：Express + MongoDB
• 文件数：350+
• 功能：用户管理、内容发布、评论系统

操作步骤：

# 1. 进入项目
cd D:\projects\api-server

# 2. 分析
fondamenta analyze

# 3. 查看API文档
type .planning/dependencies/api-routes-atomic.md

在Claude中提问：

我正在调试 /api/users/:id 接口返回500错误的问题。
根据 .planning/dependencies/api-routes-atomic.md，这个接口依赖哪些中间件和模型？
这个接口被哪些客户端调用？

示例3：团队协作工作流

背景：5人开发团队，使用Git管理代码，需要确保所有成员对代码结构有一致理解。

工作流配置：

1. 项目初始化脚本（setup.sh）

   #!/bin/bash
   echo "安装依赖..."
   npm install
   
   echo "安装Fondamenta ArchCode..."
   npm install -g fondamenta-archcode
   
   echo "分析项目..."
   fondamenta analyze
   
   echo "生成AI上下文..."
   fondamenta ai-context --all
   
   echo "完成！.planning 文件夹已生成，请提交到Git"

2. Git钩子配置（.git/hooks/pre-commit）

   #!/bin/bash
   echo "更新代码分析文档..."
   fondamenta analyze
   git add .planning/

3. CI/CD配置（.github/workflows/docs.yml）

   name: Update Code Documentation
   on:
     push:
    branches: [main]
   jobs:
     analyze:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Setup Node.js
        uses: actions/setup-node@v3
      - name: Analyze codebase
        run: npx fondamenta-archcode analyze
      - name: Commit documentation
        run: |
          git config --global user.name 'github-actions'
          git config --global user.email 'actions@github.com'
          git add .planning/
          git commit -m "Update code documentation" || exit 0
          git push

4. 新成员入职流程

   # 克隆项目
   git clone 项目地址
   cd 项目名
   
   # 项目已经有 .planning 文件夹，可以直接阅读
   # 或者重新分析确保最新
   fondamenta analyze
   
   # 开始开发
   cursor .

示例4：调试“改好一个BUG又出新BUG”的场景

问题描述：修复用户登录BUG后，发现注册功能也坏了。

调试流程：

# 1. 确保文档最新
fondamenta analyze

在Cursor中对话：

用户登录功能出现BUG：登录成功后session没有保存。
我准备修复 src/auth/login.ts 中的 session 创建逻辑。

根据 .planning/dependencies/component-graph.md：
1. login.ts 依赖哪些模块？
2. session相关的代码在哪些文件中？
3. 注册功能（register.ts）和登录共享哪些代码？

请帮我分析，如果我修改 login.ts 中的 session 创建方式，会不会影响注册功能？

AI分析后：

根据依赖图分析：
1. login.ts 依赖：
   - validateUser() 来自 auth/validation.ts
   - createSession() 来自 session/manager.ts
   - User 模型来自 models/User.ts

2. 注册功能（register.ts）也依赖：
   - createSession() 相同的函数
   - User 模型

⚠️ 风险提示：如果您修改 createSession() 的行为，会影响注册功能！

建议：
- 如果问题只在登录时出现，考虑在 login.ts 中单独处理
- 或者修改 createSession() 后，同时测试登录和注册

按照这个建议修改后，就不会出现“修好登录、坏了注册”的情况了。

10. 常见问题解决

❌ 问题1：全局安装失败

现象：

npm ERR! code EACCES
npm ERR! syscall access
npm ERR! path /usr/local/lib/node_modules

解决：

# Windows：以管理员身份运行PowerShell
# Mac/Linux：使用sudo
sudo npm install -g fondamenta-archcode

❌ 问题2：分析时卡住

现象：进度条长时间不动

解决：

# 按 Ctrl+C 取消
# 清理缓存后重试
npm cache clean --force
fondamenta analyze --force

❌ 问题3：生成的文档不完整

现象：某些文件没有被分析到

解决：

# 检查文件扩展名是否被支持
fondamenta analyze --ext "js,jsx,ts,tsx,vue" --verbose

# 排除干扰目录
fondamenta analyze --ignore "node_modules,dist,.next,out" --force

❌ 问题4：监控模式不生效

现象：修改文件后文档没有自动更新

解决：

# 检查监控的目录是否正确
fondamenta watch --src ./src --verbose

# 某些编辑器（如VSCode）的保存方式可能触发多次更新，属正常现象

❌ 问题5：AI说“无法读取文件”

现象：在Cursor/Claude中引用文件时，AI提示无法访问

解决：

# 方法1：确保文件存在
dir .planning/DEPENDENCY-MAP.md

# 方法2：直接复制内容给AI
cat .planning/DEPENDENCY-MAP.md | clip
# 然后粘贴到对话中

❌ 问题6：命令找不到（全局安装后）

现象：

fondamenta : 无法将“fondamenta”项识别为 cmdlet、函数、脚本文件或可运行程序的名称。

解决：

# 检查npm全局安装路径是否在PATH环境变量中
npm config get prefix
# 输出类似 C:\Users\用户名\AppData\Roaming\npm

# 手动添加该路径到系统PATH
# 或者重新安装，安装程序会自动配置PATH

❌ 问题7：分析速度慢

现象：分析时间超过10秒

解决：

# 排除不必要的目录
fondamenta analyze --ignore "node_modules,dist,.next,coverage,__tests__"

# 使用--force避免缓存问题
fondamenta analyze --force

❌ 问题8：想要清理生成的文档

现象：想要重新开始或删除所有文档

解决：

# 删除.planning文件夹
Remove-Item -Path .planning -Recurse -Force

# 重新分析
fondamenta analyze

11. 总结与建议

11.1 Fondamenta ArchCode 的核心价值

通过本教程的详细讲解，相信你已经了解到Fondamenta ArchCode的几大核心优势：

1. 零依赖、极简配置 - 无需数据库、无需服务器、无需MCP协议，5分钟就能上手使用
2. 超快速分析 - 1000+文件的项目只需3秒，不会打断开发节奏
3. 框架感知 - 能理解Next.js的路由、组件类型、认证模式、数据获取逻辑
4. AI友好 - 生成结构化的Markdown文件，任何AI工具都能直接读取
5. 人类可读 - 开发者也能直接阅读文档，团队协作更顺畅
6. Git友好 - 文本文件，可以提交到版本库，团队共享代码理解

11.2 适合什么样的项目和团队？

11.3 日常使用建议

每日工作流：

# 早上开始工作前，更新文档
fondamenta analyze

# 开发过程中遇到复杂问题，先查看依赖图
type .planning/DEPENDENCY-MAP.md

# 修改代码后，查看影响范围
fondamenta diff

# 提交代码前，更新AI上下文
fondamenta ai-context --all

调试工作流：

1. 遇到BUG，先运行 fondamenta analyze 确保文档最新
2. 在AI中引用相关文档，建立上下文
3. 让AI分析问题可能的原因和影响范围
4. 按照AI建议修改，避免“修好一个又坏一个”
5. 修改后运行 fondamenta diff 验证影响

团队协作建议：

1. 将 .planning 文件夹提交到Git仓库
2. 在CI/CD中自动更新文档（参考示例3）
3. 新成员入职时，先阅读 .planning 文档了解项目
4. Code Review时参考依赖图，评估修改影响

11.4 与其他工具搭配建议

11.5 结语

如果你正在被“AI不理解代码结构”、“改好一个BUG又出现新的”、“团队协作代码理解困难”这些问题困扰，Fondamenta ArchCode 是一个值得尝试的解决方案。

它的设计理念很简单：让AI能直接读取的结构化文档，而不是复杂的API服务器。正是这种“少即是多”的理念，让它成为目前最容易上手的代码分析工具。

现在就去你的项目里试试吧！只需几分钟，你就能感受到AI理解代码能力的提升。

📚 附录：命令速查表

教程信息：

• 工具版本：fondamenta-archcode@0.0.7
• 最后更新：2026年3月11日
• 作者：[根据你的信息填写]
• 转载请注明出处

太好了！Fondamenta ArchCode 全局安装成功！ 🎉

现在你已经拥有了一个超级轻量但功能强大的代码分析工具。接下来，跟着我做几个简单步骤，就能让你的AI助手真正理解你的代码。

🚀 立即开始使用

第一步：进入你的项目目录

cd Z:\www\wwwroot\ws.wnmax.com

第二步：运行分析（只需3秒）

fondamenta analyze

你会看到类似这样的输出：

🔍 Analyzing codebase...
📁 Scanning files... (找到你的文件)
✅ Analysis complete! Generated files in: Z:\www\wwwroot\ws.wnmax.com\.planning

第三步：查看生成的文档

# 看看生成了哪些文件
dir .planning

你会看到 DEPENDENCY-MAP.md 和 dependencies/ 文件夹，里面全是结构化的Markdown文档。

第四步：在Trae中使用

现在打开Trae，你可以这样提问：

新手问题：

请阅读 .planning/DEPENDENCY-MAP.md，给我介绍一下这个项目的整体架构

调试问题：

我在 [你的文件路径] 遇到了一个BUG，请根据 .planning/dependencies/component-graph.md 告诉我：
1. 这个文件依赖哪些模块？
2. 修改它会影响哪些地方？

📝 常用命令速记

🎯 现在就可以体验

进入你的项目目录，运行 fondamenta analyze，3秒后你就能在 .planning 文件夹里看到完整的代码分析文档。然后在Trae中随便问一个关于项目结构的问题，你会立刻感受到AI理解的深度变化！