1. 创建 Skill 文件（推荐）

在项目的 .claude/skills/ 目录下创建一个新的 Markdown 文件，例如 tech-stack-guide.md。

bash

mkdir -p .claude/skills
touch .claude/skills/tech-stack-guide.md

---

2. 编写 Skill 内容

文件内容分为 YAML 元数据 和 Markdown 正文，正文中详细描述技术栈选择、优先级和禁止项。

markdown

 

---
name: tech-stack-guide
description: 定义本项目遵循 Jakarta EE 11 标准的三层架构：Jakarta Faces + JS/CSS（前端）、Jakarta Enterprise Beans（业务逻辑层）、Jakarta Persistence / JDBC（数据持久层）。
triggers:
  - 编程
  - 代码
  - JSF
  - EJB
  - 数据库
  - Jakarta
---

# 项目技术架构规范（Jakarta EE 11）

本项目严格遵循 **Jakarta EE 11** 标准，采用三层架构。每个业务/功能模块都必须包含以下三层，并全部基于 Jakarta EE 11 API。

## 1. 前端展示层（Jakarta Faces + JavaScript/CSS）
- 使用 **Jakarta Faces**（原 JSF）构建用户界面。
- **禁止**使用任何第三方 JSF 组件库（如 PrimeFaces、RichFaces 等）。
- 页面交互使用原生 **JavaScript** 和 **CSS**，不得引入其他前端框架（如 jQuery、React）。
- Jakarta Faces 页面仅使用官方标准命名空间：
  ```xml
  xmlns:h="https://jakarta.ee/xml/ns/jsf/html"
  xmlns:f="https://jakarta.ee/xml/ns/jsf/core"
  xmlns:ui="https://jakarta.ee/xml/ns/jsf/facelets"

- 托管 Bean 使用 @jakarta.inject.Named、@jakarta.faces.view.ViewScoped 等 Jakarta EE 注解。

## 2. 业务逻辑层（Jakarta Enterprise Beans）
- 使用 **EJB**（Session Beans，如 `@Stateless`）实现业务逻辑和工作流编排。
- 采用无状态会话 Bean（@jakarta.ejb.Stateless）或有状态会话 Bean（@jakarta.ejb.Stateful）封装业务操作。
- 每个功能模块的业务逻辑必须封装在 EJB 中，不允许在 JSF 托管 Bean 中编写复杂业务逻辑。
- 如需轻量化，可使用 CDI Bean（@jakarta.enterprise.context.ApplicationScoped 等），但须符合 Jakarta EE 11 规范。

## 3. 数据持久层
- 默认使用 Jakarta Persistence（原 JPA）进行对象关系映射，通过 EntityManager 操作数据库。
- 实体类使用 @jakarta.persistence.Entity、@jakarta.persistence.Table 等注解。
- 仅在 JPA 无法满足性能或特殊需求时，才允许使用原生 **JDBC**，且必须在代码注释中明确说明原因。
- 数据库访问统一由 EJB 层调用，前端不直接操作数据库。

## 生成代码时的要求
- 当用户要求实现某个功能时，必须同时生成符合上述三层规范的代码，且全部使用 Jakarta EE 11 API（包名以 jakarta.* 开头）。
- 示例：用户要求“添加用户注册功能”，应生成：
  - Jakarta Faces 页面（注册表单，纯标准组件 + 原生 JS/CSS）
  - EJB（`UserService` 或类似，包含注册业务逻辑）
  - JPA 实体（User）和相应的 Repository 或直接使用 EntityManager
- 如果用户未明确指定具体实现细节，默认按此架构生成完整的三层代码。

3. 让 Claude Code 加载该 Skill

• 创建后，Claude Code 会自动扫描 .claude/skills/ 中的文件。

• 当你在对话中提出与“编程”、“代码”、“JSF”等触发关键词相关的问题时，该 skill 会被自动激活，Claude Code 将遵循其中的指令。

• 你也可以手动激活：在对话中输入 /skill tech-stack-guide。

---

4. 可选：使用项目级指令文件

如果不想用 skill，也可以创建 .claude/instructions.md（如果 Claude Code 支持该文件），写入类似的技术栈约束。但 skill 更灵活，支持触发条件和命名空间隔离。

---

5. 验证生效

在项目目录下启动 Claude Code，然后尝试提问：

“请帮我生成一个用户登录的 JSF 页面，并实现验证逻辑。”

Claude Code 应会：

• 生成纯 JSF 页面（无第三方库引用）。

• 将业务逻辑放入 EJB。

• 使用 JPA 进行用户验证（如果有数据库交互）。

如果生成的代码违反了规则，你可以进一步补充说明，Claude Code 会记住并调整。