Agent.md

本文件为通用编码 Agent 在处理此仓库时提供入口说明。

原则：保持轻量，只放高频规则和导航信息；详细说明优先查看 CLAUDE.md 与对应子目录文档。

---

项目概览

• 项目名称：Manulife WeApp（臻奇智荟圈）
• 技术栈：Taro 4.1.x + Vue 3 + NutUI + Pinia + Less + TailwindCSS
• 代码形态：以 JavaScript / Vue SFC 为主，非 TypeScript 仓库
• 目标平台：微信小程序为主，同时保留 H5 / 支付宝 / 百度 / 字节等平台构建脚本

---

开始前先做什么

1. 先读根目录 CLAUDE.md 了解项目级约束。
2. 如果修改范围落在某个目录下，继续读取该目录最近的 CLAUDE.md。
3. 涉及页面、组件、认证、API 时，优先查看 docs/ 下对应指南，避免重复踩坑。

就近规则优先：离目标代码最近的 CLAUDE.md 应视为该目录范围内的补充约束。

---

常用命令

pnpm install
pnpm dev:weapp
pnpm dev:h5
pnpm build:weapp
pnpm lint
pnpm test
pnpm api:generate
pnpm parse:docs:status

---

修改代码前必须知道

1. 认证链路不能随意改

关键文件：

• src/utils/openid.js
• src/utils/request.js
• src/pages/login/index.vue

项目依赖“静默认证 + 401 自动刷新”维持会话，任何认证相关改动都要先读现有实现。

2. API 成功态统一检查

所有接口调用都应通过现有 API 包装方式处理，并显式检查：

res.code === 1

3. 样式策略是混合式

• 布局、间距、排版、颜色优先用 TailwindCSS
• 组件私有样式、深层覆盖、复杂选择器再用 Less

4. 重复逻辑到第 3 次要抽

仓库约定遵循“第 3 次出现原则”，重复逻辑优先抽为 composable、公共组件或工具函数。

5. 组件对象注意响应式开销

涉及组件配置对象时，优先使用 shallowRef / markRaw 规避不必要的深层响应式。

6. 保持注释和文档完整

仓库已有明确的文档化习惯。新增复杂逻辑时补最小必要注释；若改动影响使用方式，补对应文档。

---

关键目录

• src/pages/：页面入口
• src/components/：通用组件
• src/composables/：复用逻辑
• src/api/：接口定义与调用包装
• src/stores/：状态管理
• src/utils/：基础工具、认证、请求封装
• config/：功能与权限配置
• docs/：项目文档、指南、报告、API 规范
• scripts/：脚本工具，包含 API 生成与文档解析

---

推荐阅读路径

快速熟悉项目

1. README.md
2. CLAUDE.md
3. docs/README.md

涉及具体开发时

• 页面开发：docs/guides/page-development.md
• API 集成：docs/guides/api-integration.md
• 导航处理：docs/guides/navigation.md
• 调试问题：docs/debugging.md
• 最佳实践：docs/best-practices.md

涉及历史经验时

• docs/lessons-learned/lessons-learned.md
• docs/CHANGELOG.md

---

Agent 工作建议

• 改动前先确认是否已有同类实现，尽量复用现有模式。
• 修改页面或组件时，检查目标目录下是否已有局部 CLAUDE.md。
• 涉及认证、请求链路、路由、计划书模块时，先读文档再改代码。
• 提交前至少运行与改动范围匹配的校验，例如 pnpm lint、pnpm test 或定向验证。

---

文档定位

Agent.md 是通用入口。

• 想快速知道“先看什么”：看本文件
• 想知道完整项目约束：看 CLAUDE.md
• 想知道模块细节：看对应目录下的 CLAUDE.md
• 想了解业务与历史背景：看 docs/README.md