1 analyze

① 五维项目分析

这是整个 AGENTS.md 创作流程的起点。跳过分析直接写，是 AGENTS.md 质量问题的第一大来源。 superpowers 的做法是：不先 brainstorming（理解问题和约束），绝不写代码。同理：不先分析项目，绝不写 AGENTS.md。

任务目标

通过五维分析框架，全面理解项目的战略和技术特征，输出结构化的项目画像，为后续的结构设计和内容撰写奠定基础。

核心原则

1. 先读文档，再问用户 — README、docs/、package.json、代码结构是首选信息源
2. 每个维度必须打分 — 即使信息不完整，也要给出"置信度"标记
3. 不确定就标注 — 不要凭空猜测，标记为"需确认"并向用户提问
4. 保持中立 — 分析是事实采集，不是价值判断

<HARD-GATE> 进入前必须完成

□ 已读取项目 README.md（至少前 50 行）
□ 已查看项目 /docs 目录（如存在）
□ 已查看 package.json / Cargo.toml / pyproject.toml 等配置文件
□ 已查看项目顶级目录结构（ls -la）
□ 已检查是否存在现有 AGENTS.md / CLAUDE.md / .cursorrules

如果以上任何一项未完成，先执行。这些信息是分析的原材料。

---

五维分析流程

维度 1: 产品定位分析

目的：理解项目为什么存在、解决什么问题、核心竞争力在哪。这些决定了 Agent 在工作时应该优先考虑什么。

检查清单：

• 项目的一句话描述是什么？（从 README 或用户描述中提取）
• 解决的是什么场景下的什么问题？
• 项目的目标用户/客户是谁？
• 项目的核心价值主张是什么？（比竞品好在哪）
• 项目处于什么阶段？（MVP/增长期/成熟期/维护期）

输出格式：

产品定位评分: ◐○○○○ (1/5) 至 ●●●●● (5/5)
一句话定位: [从 README 提取或用户确认]
核心价值: [该项目最独特的价值]
所处阶段: [MVP / 增长 / 成熟 / 维护]

维度 2: 目标用户分析

目的：AGENTS.md 的读者是谁？不同角色的 Agent 需要不同的行为规范。

检查清单：

• 主要的开发者画像？（个人 / 小团队 / 大团队 / 开源社区）
• 使用者是 AI Agent 还是人类开发者？还是两者混合？
• 如果是多 Agent 协作，每个 Agent 的角色是什么？
• 目标用户的编程水平？（新手 / 中级 / 高级）
• 使用场景的频率？（日常开发 / 偶发维护 / 一次性部署）

输出格式：

目标用户画像:
  - 主要用户: [开发者 / 运维 / PM / 多角色]
  - 团队规模: [个人 / 2-5人 / 5-20人 / 20+人]
  - Agent 角色: [编码助手 / 审查助手 / 部署助手 / 全栈]
  - 使用频率: [每日 / 每周 / 项目级]

维度 3: 功能边界分析

目的：定义 Agent 在项目中能做什么、不能做什么。这是 AGENTS.md 中最核心的约束部分。

检查清单：

• 项目有哪些核心功能模块？
• Agent 可以操作哪些文件/目录？
• Agent 绝对不能碰哪些文件/目录？
• Agent 可以运行哪些命令？不能运行哪些？
• Agent 可以修改哪些配置？不能修改哪些？
• Agent 可以直接生成代码还是只能提建议？
• 是否有外部 API 集成？Agent 能否调用？

输出格式：

功能边界:
  ✅ 允许的操作: [列表]
  ❌ 禁止的操作: [列表]  ← 这是最重要的部分，必须明确
  ⚠️ 需确认的操作: [列表]
  
文件访问权限:
  可读: [路径模式]
  可写: [路径模式]
  禁止访问: [路径模式]

维度 4: 安全检查分析

目的：识别项目中的安全红线，确保 AGENTS.md 包含足够的安全约束。参考 security-checklist.md 的完整清单。

检查清单：

• 项目涉及用户数据/隐私吗？（PII / 敏感数据）
• 有 API 密钥/证书/密码等凭证吗？
• 是否有部署/生产环境访问权限？
• Agent 能否访问网络？
• Agent 能否执行可能产生费用的操作？
• 是否有合规要求？（GDPR / SOC2 / HIPAA）
• 项目是否有自动化测试基础设施？
• Agent 能否修改 CI/CD 配置？

输出格式：

安全等级: [低 / 中 / 高 / 关键]
数据敏感性: [无敏感数据 / 内部数据 / 用户数据 / PII]
安全约束:
  - [约束1]
  - [约束2]
合规要求: [无 / GDPR / SOC2 / 其他]

维度 5: 架构规划分析

目的：理解项目的代码组织方式，让 AGENTS.md 能够指导 Agent 正确导航代码。参考 superpowers 的架构思维 — Agent 需要知道代码仓库的结构才能有效工作。

检查清单：

• 项目使用什么架构模式？（MVC / 分层 / 微服务 / 单体）
• 技术栈是什么？（语言 / 框架 / 数据库）
• 项目的包/模块如何组织？
• 构建工具/测试框架是什么？
• 是否有代码风格规范？（linter / formatter 配置）
• 项目根目录下的关键文件是什么？（docker-compose / Makefile / CI 配置）
• 测试文件放在哪里？（单元测试 / 集成测试 / E2E）

输出格式：

架构模式: [MVC / 分层 / 微服务 / 单体 / 混合]
技术栈:
  语言: [语言列表]
  框架: [框架列表]
  数据库: [数据库列表]
  构建工具: [构建工具]
  测试框架: [测试框架]
  
关键路径:
  - 源代码: [src/ 或 lib/ 等]
  - 测试: [tests/ 或 __tests__/ 等]
  - 配置: [config/ 或 .env 等]
  - 文档: [docs/ 或 wiki/ 等]

---

五维评分汇总

完成五维分析后，汇总为项目画像总表：

维度	评分 (1-5)	置信度	关键发现	需确认项
产品定位		高/中/低
目标用户		高/中/低
功能边界		高/中/低
安全检查		高/中/低
架构规划		高/中/低

置信度规则：

• 高：从项目文档中明确获取，无需确认
• 中：从文档中推断，需要用户confirm
• 低：文档不足以判断，必须向用户提问

---

输出：项目画像

分析阶段结束后，输出结构化的项目画像。这是后续所有阶段的输入。

# 项目画像 (project-profile.yaml)
project:
  name: <项目名>
  type: <应用 / 库 / 框架 / 工具 / 平台>
  
product:
  positioning: <一句话产品定位>
  target_users: <目标用户>
  value_proposition: <核心价值>
  stage: <项目阶段>
  
boundaries:
  allowed: [允许的操作列表]
  forbidden: [禁止的操作列表]
  uncertain: [需确认的操作列表]
  
security:
  level: <安全等级>
  data_sensitivity: <数据敏感性>
  constraints: [安全约束列表]
  
architecture:
  pattern: <架构模式>
  tech_stack: <技术栈摘要>
  key_paths: [关键路径列表]
  
gates:
  - <已识别的关键门禁>

---

与用户的交互

核心原则：先查文档，再问问题。

可以问用户的问题（仅在文档不足以判断时）：

1. "我读完了项目的 README，但对产品定位还有些模糊。我看到项目是做 X 的，但不太确定它的核心场景是 A 还是 B？"
2. "项目中有些目录我不太确定 Agent 能否访问，比如 /deploy 目录下的配置，Agent 应该能读还是不能碰？"
3. "我没找到安全检查相关的配置，项目有安全合规要求吗？比如需要处理用户敏感数据？"

不要问（可以从文档获取的）：

• ❌ "项目用什么语言？" → 读 package.json / Cargo.toml
• ❌ "项目目录结构是什么？" → ls -la 看一下
• ❌ "有没有测试？" → 找 tests/ 或 tests/ 目录