# Agents Writer Analyze

> 五维项目分析 — 从产品定位、目标用户、功能边界、安全检查、架构规划五个维度分析项目，输出结构化的项目画像，为 AGENTS.md 设计提供决策依据

- Skill: `morning-start/agents-writer-analyze` (Agent Skill)
- Install (CLI): `npx skillmds@latest add morning-start/agents-writer-analyze`
- Raw SKILL.md: https://api.skillmd.com/api/skills/morning-start/agents-writer-analyze/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: morning-start (https://skillmd.com/u/morning-start)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/morning-start/agents-writer-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](../../references/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
- **低**：文档不足以判断，必须向用户提问

---

## 输出：项目画像

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

```yaml
# 项目画像 (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__/ 目录