name: architecture-navigator description: 理解并导航DevPrep AI的7文件夹架构。当被问及代码组织、新功能放置位置、现有模块或在需要架构上下文开始开发任务时使用此技能。关键词如“where should”、“add module”、“architecture”、“structure”、“organize”、“place code”、“what modules”时自动触发。

架构导航器

概述

为DevPrep AI代码库提供即时架构智能。生成架构图，回答放置问题（“X应该放在哪里？”），并根据7文件夹结构验证代码组织。此技能消除了在对话开始时手动阅读架构文档的需要。

核心能力

1. 架构扫描

在开始开发对话或明确请求时，扫描代码库以生成实时架构图。

如何扫描：

# 从项目根目录运行架构扫描器
bash ./.claude/skills/architecture-navigator/scripts/scan_architecture.sh

扫描器将输出：

7文件夹结构：modules/、shared/、lib/、store/、types/、styles/、app/
模块列表：所有功能模块及其文件数量
关键位置：API层、状态管理、UI组件
快速统计：总文件数、模块数、组件数

何时扫描：

在开始关于架构的开发对话时
当被问及“有哪些模块？”或“结构是什么？”时
在建议新代码放置位置之前
在验证架构合规性时

输出格式： 紧凑的Markdown摘要（约50-100行），显示当前架构状态。

2. 交互式放置查询

使用7文件夹放置规则回答“X应该放在哪里？”的问题。

决策树：

是路由/页面吗？ → app/（但保持最小化，从modules/导入）
是功能特定的吗？ → modules/{feature}/
是可重用的UI/逻辑吗？ → shared/
是外部集成吗？ → lib/
是全局状态吗？ → store/
是共享类型吗？ → types/
是纯样式吗？ → styles/

示例查询和响应：

用户查询	响应
“社交登录应该放在哪里？”	`modules/auth/` - 功能特定的认证逻辑
“我应该在哪里添加支付处理？”	`modules/payments/` - 用于支付领域逻辑的新功能模块
“可重用按钮放在哪里？”	`shared/components/ui/Button.tsx` - 可重用UI组件
“Claude AI集成在哪里？”	`lib/claude/` - 外部服务集成
“购物车状态应该放在哪里？”	`store/cartStore.ts` - 全局状态管理
“API类型放在哪里？”	`types/ai/api.ts` - 共享TypeScript定义

详细规则，请参考references/architecture-rules.md，其中包括：

所有7个文件夹的完整放置规则
导入方向规则（什么可以导入什么）
禁止模式（循环依赖、错误导入）
复杂放置问题的决策树
常见示例和边缘情况

3. 模块发现

在被问及时列出现有模块并解释其用途。

如何发现模块：

# 快速模块列表
ls -1 frontend/src/modules/

# 带文件计数
find frontend/src/modules/ -mindepth 1 -maxdepth 1 -type d -exec sh -c 'echo -n "{}:" && find "{}" -name "*.ts*" | wc -l' \;

常见问题：

“有哪些模块？” → 运行模块发现
“认证功能在哪里？” → 检查modules/中与认证相关的文件夹
“实现了哪些功能？” → 扫描modules/目录

4. 架构验证

验证代码是否遵循7文件夹结构规则。

检查内容：

✅ app/中的路由是最小化的（仅导入）
✅ 业务逻辑在modules/中，不在app/中
✅ 共享组件在shared/中，不重复
✅ 外部集成在lib/中
✅ 全局状态在store/中
✅ 导入遵循允许的方向（参见architecture-rules.md）

验证命令：

# 检查app/中是否有业务逻辑（应该是最小化的）
grep -r "useState\|useEffect\|async function" frontend/src/app/

# 检查跨模块导入（禁止）
grep -r "from.*modules/" frontend/src/modules/

# 检查模块是否从shared导入（允许）
grep -r "from.*shared/" frontend/src/modules/

工作流程：使用此技能

场景1：对话开始

当开发对话开始时，主动扫描架构：

运行scripts/scan_architecture.sh生成当前架构图
简洁地呈现该图（不要用细节压倒用户）
将此上下文用于后续的放置问题

场景2：放置问题

当被问及“X应该放在哪里？”时：

识别代码的性质（功能、可重用、集成等）
应用references/architecture-rules.md中的决策树
提供具体的路径建议
解释原因（适用哪条规则）

示例：

用户：“我应该在哪里添加OAuth认证？”

响应：
OAuth认证应该放在`modules/auth/oauth/`中：
- 它是功能特定的（认证领域）
- 它属于modules/（不能在其他功能中重用）
- 结构：modules/auth/oauth/GoogleAuth.tsx、OAuthProvider.tsx等

OAuth客户端设置（SDK包装器）应该放在`lib/oauth/client.ts`中（外部集成）。

场景3：新功能模块

当创建新功能模块时：

确认它确实是功能（领域特定，非跨领域）
创建结构：modules/{feature-name}/

推荐典型结构：

modules/{feature}/
├── components/     - 功能特定UI
├── hooks/          - 功能特定钩子
├── utils/          - 功能特定工具
└── types.ts        - 功能特定类型（如果不共享）

提醒导入规则（可以从shared/、lib/、store/、types/导入）

自动触发关键词

检测到以下短语时，此技能自动激活：

“where should”（应该放在哪里）
“add module”（添加模块）
“architecture”（架构）
“structure”（结构）
“organize”（组织）
“place code”（放置代码）
“what modules”（有哪些模块）
“where does [X] live”（[X]在哪里）
“where’s the API”（API在哪里）
“folder structure”（文件夹结构）

手动调用： 使用/architecture或明确请求“扫描架构”。

资源

scripts/scan_architecture.sh

快速bash脚本，扫描7文件夹结构并生成Markdown架构图。输出模块列表、关键位置和快速统计。

用法：

bash scripts/scan_architecture.sh [project-root]

输出： 紧凑的Markdown摘要（约50-100行），适合加载到上下文中。

references/architecture-rules.md

7文件夹架构的完整放置规则。在以下情况下参考此文档：

回答复杂的放置问题
验证架构合规性
解释导入方向规则
处理边缘情况或模糊场景

关键部分：

7文件夹结构概述
每个文件夹的详细放置规则
导入方向规则（什么可以导入什么）
禁止模式
放置决策树
常见示例表

最佳实践

从扫描开始：在对话开始时生成架构图以获取上下文
具体明确：始终提供确切路径，不仅仅是文件夹名称
解释推理：不要只说“放在modules/中”，解释原因
参考规则：指向architecture-rules.md以获得详细理由
验证导入：检查建议的放置是否尊重导入方向规则
检测偏差：标记实际代码结构与文档架构的偏差
保持简洁：架构图应可扫描（约50-100行）

使用示例

用户：“我想添加一个通知系统，在整个应用中显示toast消息。”

响应：

让我先扫描当前架构：

bash ./.claude/skills/architecture-navigator/scripts/scan_architecture.sh

[架构图输出]

对于具有toast消息的全局通知系统：

Toast UI组件 → shared/components/Toast.tsx（可重用UI）
通知状态 → store/uiStore.ts（管理活动toasts的全局状态）
Toast钩子 → shared/hooks/useToast.ts（便捷API：useToast().show()）

推理：

Toast组件在所有功能中可重用 → shared/
通知状态是全局的（非功能特定） → store/
钩子提供符合人体工程学的API且可重用 → shared/

导入流程：

功能从shared/hooks/调用useToast()
钩子访问store/uiStore.ts
钩子渲染shared/components/Toast.tsx

这遵循架构规则：modules/ → shared/ → store/（允许的导入方向）。