Stats
Actions
Tags
From team-standards
Scans project code to generate a structured Markdown profile for AI agents: project overview, business context, and coding conventions. Useful for creating standardized project knowledge for AI-assisted development.
How this skill is triggered — by the user, by Claude, or both
Slash command
/team-standards:generate-project-profileThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
**代码感知是一切 AI 辅助开发的基石。** 本 Skill 将项目代码转化为结构化 Markdown 文档，作为需求分析、方案设计、方案审查等后续环节的知识上下文。
代码感知是一切 AI 辅助开发的基石。 本 Skill 将项目代码转化为结构化 Markdown 文档，作为需求分析、方案设计、方案审查等后续环节的知识上下文。
核心思想：
用户说以下任意一种时，必须调用本 Skill：
| 维度 | init-project-docs | generate-project-profile |
|---|---|---|
| 目标读者 | 人（开发者阅读理解项目） | AI Agent（程序化消费知识上下文） |
| 输出文件 | 3 份文档（概要 + 架构 + 开发参考） | 3 份文档（索引 + 业务上下文 + 编码规范） |
| 侧重点 | 业务流程图、架构图、开发场景速查 | 结构化能力清单、服务交互契约、实体状态机 |
| 使用方式 | 人工阅读 | 注入 Agent Context / 向量化分片检索 / 多服务画像拼接为知识图谱 |
两者可以共存，不冲突。
flowchart TD
A(["收到生成项目画像指令"]) --> B["探索项目根目录<br/>识别构建工具和语言"]
B --> C["读取构建配置<br/>pom.xml / build.gradle / package.json"]
C --> D["扫描项目目录结构<br/>识别模块划分"]
D --> E["读取 Entity/Model 层<br/>提取数据模型和状态枚举"]
E --> F["读取 Service 层<br/>提取能力清单，按业务域分组"]
F --> G["读取 Controller/API 层<br/>提取对外暴露接口"]
G --> G2["扫描 Feign/HTTP Client<br/>提取对外调用的下游服务"]
G2 --> G3["扫描消息监听/发布<br/>提取事件契约"]
G3 --> H["读取配置文件<br/>识别服务注册名称"]
H --> I["归纳核心业务流程<br/>识别实体状态机"]
I --> I2["扫描约束与扩展点<br/>事务/幂等/鉴权/状态守卫"]
I2 --> J["归纳编码约定<br/>提取典型代码范式"]
J --> K{"docs/ 目录存在?"}
K -->|否| L["创建 docs/ 目录"]
K -->|是| M["检查已有画像文件"]
L --> N["生成 3 个文件"]
M --> N
N --> N1["project-profile.md<br/>索引 + 项目概述 + 技术栈"]
N --> N2["business-context.md<br/>数据模型/能力/流程/约束/接口/服务调用/事件"]
N --> N3["coding-conventions.md<br/>编码约定 + 配置概要"]
N1 --> O(["输出文件路径，告知用户完成"])
N2 --> O
N3 --> O
一个文件塞所有维度，LLM 会把无关信息"创造性关联"，产生幻觉。 比如编码约定里的 Result<T> 包装模式，在做需求分析时可能被 AI 编出"当前已有统一退款结果包装类"的结论。
解法：每个消费阶段只给它需要的那份文件，物理隔离无关信息。
docs/
├── project-profile.md ← 索引文件（轻量，每次都加载）
├── business-context.md ← 业务上下文（需求分析 / 方案设计加载）
└── coding-conventions.md ← 编码规范（代码生成阶段加载）
| 文件 | 消费阶段 | 内容 | 信噪比 |
|---|---|---|---|
project-profile.md | 每次 | 项目概述 + 技术栈 + 指向其他文件的引用 | 极高（~500 token） |
business-context.md | 需求分析 / 方案设计 | 数据模型与状态机 + 业务能力 + 业务流程 + 约束 + 接口 + 服务调用 + 事件 | 高（~3K-5K token，全是业务信息） |
coding-conventions.md | 代码生成 | 编码约定 + 配置概要 | 高（~1K-2K token，全是编码规范） |
project-profile.md（索引）
| # | 维度 | 说明 |
|---|---|---|
| 1 | 项目概述 | 项目名、用途、语言版本、模块列表、服务注册名称 |
| 2 | 技术栈 | 框架、中间件、版本 |
business-context.md（业务上下文）
| # | 维度 | 数据来源 | 说明 |
|---|---|---|---|
| 3 | 数据模型与状态机 | Entity + 枚举类 | 实体、核心字段、关联关系、实体状态流转 |
| 4 | 业务能力清单 | Service 接口/类 | 按业务域分组，标注业务语义 |
| 5 | 核心业务流程 | Service 调用链推断 | 关键流程 + 状态变迁 + 事件。每步附证据来源 |
| 6 | 关键约束与扩展点 | Service + AOP + 配置 | 事务边界、幂等点、鉴权、状态守卫、失败补偿 |
| 7 | 对外暴露接口 | Controller 层 | Method + URL + 入参 + 出参 |
| 8 | 对外调用服务 | FeignClient / HTTP Client | 本服务调用了谁 |
| 9 | 事件与消息契约 | MQ Listener + Publisher | 发布/消费的事件 |
coding-conventions.md（编码规范）
| # | 维度 | 数据来源 | 说明 |
|---|---|---|---|
| 10 | 编码约定 | 代码归纳 | 命名规范、异常处理、通用基类 + 代码片段 |
| 11 | 配置概要 | application*.yml | 仅业务相关配置 |
每个输出文件对应一个模板：
template.md → 生成 docs/project-profile.md（索引）business-context-template.md → 生成 docs/business-context.md（业务上下文）coding-conventions-template.md → 生成 docs/coding-conventions.md（编码规范）| v1 维度 | v2 去向 | 原因 |
|---|---|---|
| 3. 项目结构（目录树） | 删除 | AI 可自行 ls/Glob，目录树占 token 但不帮助理解业务 |
| 4. 分层架构 | 删除 | "DDD-lite / MVC"标签对需求分析无价值，编码约定中已含分层规则 |
| 5. 数据模型 | 升级为 3. 数据模型与状态机 | 增加实体状态枚举和状态流转 |
| 6. Service 能力清单 | 升级为 4. 业务能力清单 | 按业务域分组 + 业务语义标注 |
| 7. API 接口 | 升级为 7. 对外暴露接口 | 强调"对外暴露"语义，区分于调用下游 |
| 8. 外部依赖服务 | 拆分为 8 + 9 | 拆为"对外调用服务"（HTTP）和"事件契约"（MQ），为图谱拼接提供边 |
| 9. 配置概要 | 精简为 11. 配置概要 | 只保留业务配置，去掉 server.port 等噪音 |
| 10. 编码约定 | 保留为 10. 编码约定 | 不变 |
| （无） | 新增 5. 核心业务流程 | 回答"业务怎么跑"，附证据来源 |
| （无） | 新增 6. 关键约束与扩展点 | 回答"改这里容易炸在哪、改动半径多大" |
A 组回答"这个系统是什么、能做什么业务、业务怎么跑、碰什么会炸"。是 AI 做需求影响分析的核心依据。
维度 1 — 项目概述
必须包含 服务注册名称（如 Spring Cloud 的 spring.application.name），这是跨服务图谱拼接的主键。
维度 2 — 技术栈
保持不变，用于方案设计阶段判断技术可行性。
维度 3 — 数据模型与状态机
v1 只列字段和关联。v2 增加实体状态枚举和状态流转：
| 实体 | 状态枚举 | 流转路径 |
|------|---------|---------|
| Order | CREATED → PAID → SHIPPED → COMPLETED | 正常流程 |
| Order | PAID → REFUNDING → REFUNDED | 退款流程 |
| Order | CREATED → CANCELLED | 取消流程 |
为什么关键：退货需求的第一个问题就是"订单有哪些状态，退货应该插入到哪个状态之后"。没有状态机，AI 只能猜。
维度 4 — 业务能力清单
v1 按 Service 类列方法签名。v2 改为按业务域分组，每个能力附一句话业务语义：
### 订单域
| 能力 | Service#Method | 说明 |
|------|---------------|------|
| 创建订单 | OrderService#placeOrder | 校验库存 → 锁库存 → 创建订单 → 发布 ORDER_CREATED 事件 |
| 取消订单 | OrderService#cancelOrder | 仅 CREATED 状态可取消 → 释放库存 → 发布 ORDER_CANCELLED |
| 查询订单 | OrderService#getOrderDetail | 支持按 ID / 用户 / 状态查询 |
### 支付域
| 能力 | Service#Method | 说明 |
|------|---------------|------|
| 发起支付 | PaymentService#createPayment | 调用第三方支付网关 → 更新订单状态为 PAID |
为什么关键：AI 看到"退货退款需求"时，能直接定位到订单域和支付域的现有能力，判断哪些能复用、哪些需新增。
维度 5 — 核心业务流程（新增）
用文字（非 Mermaid）简明描述 2-5 个核心业务流程，标注涉及的 Service、状态变迁和事件。每个流程末尾必须附证据来源：
### 下单流程
1. 用户提交订单 → OrderController#placeOrder
2. OrderService 校验库存 → 调用 inventory-service 锁定库存
3. 创建 Order（状态 CREATED）→ 写入 t_order
4. 发布事件 ORDER_CREATED → 通知 notification-service
> 证据来源：OrderServiceImpl#placeOrder, InventoryFeignClient#lockStock, OrderCreatedProducer#send
为什么关键：这是连接所有维度的"胶水"。有了流程，AI 才能理解"退货退款"应该在哪个流程之后发生，涉及哪些 Service、改哪些状态、发什么事件。
证据锚点规则：维度 3（状态机）、4（能力清单）、5（业务流程）、6（约束）中涉及推断的内容，必须在段落末尾标注 > 证据来源：{类名#方法名} 或 > 证据来源：{文件路径}。这让下游 Agent 能区分"从代码中提取的事实"和"推断的结论"。
维度 6 — 关键约束与扩展点（新增）
回答"这个需求该插在哪、最容易炸在哪、改动半径有多大"：
### 事务边界
| 方法 | 事务范围 | 说明 |
|------|---------|------|
| OrderService#placeOrder | 创建订单 + 订单明细在同一事务 | 库存锁定通过 Feign 调用，不在事务内 |
| PaymentService#handleCallback | 更新 Payment + 更新 Order 在同一事务 | 事件发布在事务提交后 |
### 幂等点
| 接口/方法 | 幂等键 | 机制 |
|-----------|--------|------|
| PaymentController#callback | paymentId | 数据库唯一索引 |
| OrderService#cancelOrder | orderId + status | 状态守卫（仅 CREATED 可取消） |
### 鉴权入口
| 接口 | 鉴权方式 | 说明 |
|------|---------|------|
| /api/orders/** | JWT Token | 通过 SecurityFilter 统一校验 |
| /api/internal/** | 服务间签名 | 仅内部调用，非用户接口 |
### 状态变更守卫
| 实体 | 守卫规则 | 违反后果 |
|------|---------|---------|
| Order | CREATED → CANCELLED 仅允许用户主动或超时 | 抛 IllegalStateException |
| Order | PAID 后不可直接 CANCELLED，必须走退款流程 | 抛 BusinessException |
### 外部依赖失败补偿
| 外部依赖 | 失败处理 | 说明 |
|---------|---------|------|
| inventory-service 锁库存 | 失败则订单创建失败，无需补偿 | 强依赖 |
| payment-gateway | 超时则标记 PENDING，定时任务轮询查询 | 最终一致 |
### 不可轻易改动的核心规则
- 订单金额一旦创建不可修改（审计要求）
- 支付回调必须验签（安全要求）
- ...
> 证据来源：OrderServiceImpl#placeOrder, SecurityConfig, PaymentCallbackController#callback
为什么关键：需求分析时，AI 不仅要知道"有什么能力"，还要知道"碰什么会炸"。退货需求必然涉及状态变更守卫、事务边界调整、新增幂等点，没有这个维度 AI 只能盲猜风险点。
维度 7 — 对外暴露接口
沿用原 API 接口维度，但明确语义为"本服务对外暴露的能力"。
维度 8 — 对外调用服务（从原"外部依赖"拆出）
专门描述本服务调用了哪些其他服务：
| 目标服务 | 调用方式 | 接口 | 用途 |
|---------|---------|------|------|
| inventory-service | Feign | POST /api/inventory/lock | 下单时锁定库存 |
| inventory-service | Feign | POST /api/inventory/release | 取消订单时释放库存 |
| payment-gateway | HTTP | POST /api/pay/create | 发起第三方支付 |
为什么关键：这是图谱的"出边"。AI 做退货需求分析时，能立刻知道 order-service 调了 inventory-service 和 payment-gateway，退货流程大概率也需要调这两个。
维度 9 — 事件与消息契约（从原"外部依赖"拆出）
### 发布的事件
| Topic/Exchange | 事件类型 | Payload 关键字段 | 触发条件 |
|----------------|---------|-----------------|---------|
| order-events | ORDER_CREATED | orderId, userId, amount | 订单创建成功 |
| order-events | ORDER_PAID | orderId, paymentId | 支付回调成功 |
| order-events | ORDER_CANCELLED | orderId, reason | 用户取消订单 |
### 消费的事件
| Topic/Exchange | 事件类型 | 来源服务 | 处理逻辑 |
|----------------|---------|---------|---------|
| payment-events | PAYMENT_SUCCESS | payment-service | 更新订单状态为 PAID |
为什么关键：这是图谱的"事件边"。退货需求需要发布 ORDER_REFUNDED 事件，notification-service 可能需要消费它来发退款通知。没有事件契约，AI 不知道现有的事件体系怎么设计。
维度 10（编码约定）和维度 11（配置概要）在需求分析阶段价值低，但在方案设计和代码生成阶段需要。保留但降级到最后。
配置概要精简规则：只保留业务相关配置（功能开关、限额、重试次数、超时时间等），去掉 server.port、spring.datasource.url 等纯基础设施配置。
每个 profile 通过以下字段成为图谱节点：
order-service）| 边类型 | 数据来源 | 方向 |
|---|---|---|
| 同步调用 | 维度 8（对外调用服务）→ 目标服务的维度 7（对外暴露接口） | A → B |
| 事件驱动 | 维度 9 发布侧 → 维度 9 消费侧 | A ⇢ B（虚线表示异步） |
| 共享概念 | 维度 3 中出现相同实体名或外键引用 | A ⇔ B（双向） |
order-service payment-service inventory-service
┌─────────────────┐ ┌──────────────────┐ ┌──────────────────┐
│ 维度4: 创建订单 │──Feign──→ │ 维度6: POST /pay │ │ 维度6: POST /lock │
│ 维度4: 取消订单 │──Feign──→ │ │←Feign── │ │
│ 维度8: ORDER_PAID │⇠ 事件 ⇠ │ 维度8: PAY_SUCCESS │ │ │
│ 维度8: ORDER_CREATED│⇢ 事件 ⇢ │ │ │ 维度8: ORDER_CREATED│
│ │──Feign──→ │ │ │ (消费→扣减库存) │
└─────────────────┘ └──────────────────┘ └──────────────────┘
退货需求影响分析时，AI 可以沿着这些边自动推导：
这个维度需要从代码中归纳，不是简单提取。重点关注：
Result<T> / ResponseEntity / 裸返回？必须附 2-3 个从项目中提取的真实代码片段，展示项目的"标准写法"。
*** 替代本 Skill 不限定语言和框架。根据项目实际情况调整：
| 项目类型 | 构建配置 | 数据模型来源 | Service 来源 | API 来源 | 服务调用来源 | 事件来源 |
|---|---|---|---|---|---|---|
| Java Spring | pom.xml | @Entity / @Table | @Service 类 | @RestController | @FeignClient / RestTemplate | @RabbitListener / @KafkaListener |
| Java MyBatis | pom.xml | Mapper XML / Entity | @Service 类 | @RestController | @FeignClient / RestTemplate | @RabbitListener |
| Node.js | package.json | Prisma / Mongoose | service/ 目录 | router/ / controller/ | axios / fetch 调用 | event emitter / MQ consumer |
| Python Django | requirements.txt | models.py | views.py / services/ | urls.py | requests / httpx | celery tasks |
| Go | go.mod | model/ 目录 | service/ 目录 | handler/ / router/ | HTTP client | goroutine / channel |
| Vue/React | package.json | 不适用 | store/ / composables/ | api/ 目录 | 不适用 | 不适用 |
前端项目：跳过维度 3（数据模型）、5（业务流程）、7（对外调用）、8（事件契约），标注「不适用」。
spring.application.name），这是图谱节点 IDI*.java），按业务域分组，减少 token 消耗@Transactional 找事务边界、唯一索引/幂等键、SecurityConfig/Filter 找鉴权入口、状态守卫（if status != XXX throw）、外部调用的重试/降级/补偿逻辑=、,、/、<、>、(、)、[、]、: 时必须加引号< > 改用文字（如：大于、小于、请求体、响应体）classDiagram 方法名不含中文design-doc-required> 证据来源：{ClassName#methodName} 或 > 证据来源：{file_path}npx claudepluginhub exception-coder/team-standards --plugin team-standardsProvides behavioral guidelines to reduce common LLM coding mistakes, focusing on simplicity, surgical changes, assumption surfacing, and verifiable success criteria.
Searches, retrieves, and installs Agent Skills from prompts.chat registry using MCP tools like search_skills and get_skill. Activates for finding skills, browsing catalogs, or extending Claude.
Creates, edits, and optimizes skills for Claude Code, including drafting, evaluating with test prompts, iterating on performance, and improving skill descriptions for better triggering accuracy.