项目里的Agent Skills 体系理解面向研发的 AI 工程体系包括： 1、提示词工程.agents/context

面向研发的 AI 工程体系包括：

1、提示词工程.agents/context 知识面 + SKILL.md 结构化 workflow + Harness 版本管理

2、Agent Skills 多个任务级的 workflow 覆盖代码审查、性能守卫、样式迁移、埋点生成、迭代管理等

3、AI DevOps 工具链：ai:review → ai:check → ai:preflight → ai:invest

核心理念：

把 AI Agent 视为仓库的一等公民开发者，通过结构化的知识面 + workflow 让 AI 能稳定、可复现的参与开发的全流程。

Agent Harness 架构

以确定性系统，驾驭非确定性智能

核心理念：不是直接写 prompt，而是把 prompt 工程结构化为仓库内可版本管理的知识面（Harness）

开发者正从“亲手编写代码”转向“定义目标、设计约束、掌控节奏并进行验收”的流程管理者

.agents/context/ — 被动加载的知识面

为 AI Agent 提供压缩后的稳定事实摘要

architecture-overview.md → 架构概述，Agent 在修改代码时自动理解 FSD 分层规则，避免违反依赖方向
coding-conventions.md → Agent 生成代码时自动遵循命名、导入、React、MobX、样式、注释、性能、commit等约定
tech-stack.md → Agent 知道项目用什么技术栈，不会引入不兼容的库
......

触发方式：AI Agent 自动加载。

.agents/skills/ — 按场景自动激活的 Workflow

任务级 workflow，每个 skill 都是一个结构化的提示词模板：

eslint-autofix/SKILL.md （比如这个就是用于修改 ts/tsx/js/jsx 文件后的标准 lint 流程）
harsh-current-branch-review/SKILL.md (比如这个就是对于当前工作区里未提交的 Git 代码改动做严格的代码审查)
demo-tailwindcss/SKILL.md （比如这个就是定义了TailwindCSS 在编写/重构/评审时候的规则）
......

每个 Skill 的 description 字段定义了触发条件，AI Agent 会根据当前任务自动匹配。比如：

对 AI 说的话	自动激活的 Skill
"帮我 review 一下当前的改动"	`harsh-current-branch-review`
"改完代码了，处理一下 lint"	`eslint-autofix`
"检查下有没有内存泄漏"	`performance-guard`
"写个 TailwindCSS 的样式"	`project-tailwindcss`
"帮我补一下埋点"	`web-reporting`

触发方式：用自然语言和 AI 对话时候，AI Agent 会按照 description 自动匹配，判断是否激活

比如eslint-autofix，它的触发逻辑是：Agent 每次修改完 .ts/.tsx/.js/.jsx 文件后，自动按这个 workflow 跑 eslint --fix。你不需要说"跑一下 eslint-autofix skill"，Agent 改完代码就会自动执行。

AGENTS.md 目录级别的导航协议

就像是给 AI Agent 看的说明书，每个目录下的 AGENTS.md 就是在告诉 AI Agent

这个目录是做什么的
应该先看哪些文件
哪些文件不能改

触发方式：AI Agent 进入目录时自动读取。

举个实际场景

比如你用 Claude Code 打开这个仓库，然后说：

"帮我在 packages/demo 里新增一个 Button 组件"

Claude Code 会：

自动读取 packages/demo/AGENTS.md
从中得知：先查 atoms/、blocks/ 有没有现成的 → 用 pnpm run create 创建 → 目录用 PascalCase → 优先用 Tailwind CSS
按照这些规则执行

如果没有这个 AGENTS.md，Claude Code 可能会：

不知道该用 pnpm run create 还是手动建目录
不知道样式该用 Tailwind 还是 CSS Modules
不知道要先检查是否已有现成组件

AI DevOps 工具链

scripts/ai-* 目录下的工具是通过 pnpm 命令手动触发的：

# AI 预检流水线（串联 review + check） scripts/ai-preflight
pnpm ai:preflight

# AI 代码审查（分析当前分支 diff） scripts/ai-review
pnpm ai:review

# AI 影响面分析 + 自动化检查 scripts/ai-check
pnpm ai:check

# AI 问题调查助手 scripts/ai-investigate
pnpm ai:investigate --desc "聊天页面白屏" --screenshot ./bug.png

触发方式：开发者/CI 手动执行 pnpm 命令时候。它们是纯 Node.js 程序，不依赖 AI 大模型，而是做规则性静态分析（FSD 分层、SKILL 结构校验、影响面分类等）。

Skills 同步机制（把 Skills 分发给不同 AI 工具）

因为不同 AI 工具读取 Skill 的目录位置不一样，所以有一套同步机制：

1、将 .agents/skills/ 同步到不同 AI 工具的目录格式（如 Claude Code 的 .claude/skills/）

2、pnpm install 后自动同步 skills

3、支持多 Agent 适配：Claude Code、Cursor 等

# 手动同步（默认同步到 Claude Code）
pnpm skills:sync

# 同步到指定工具
pnpm skills:sync -- claude-code

同步规则：

源（唯一事实源）：.agents/skills/<skill-name>/SKILL.md
    
目标（自动生成）：.claude/skills/<skill-name>/SKILL.md（Claude Code 用）
    
pnpm install 时自动同步一次（CI 和生产环境跳过）

触发方式：pnpm install 或 pnpm skills:sync

每个 Skill 必须遵循标准结构比如 AGENTS.md

name + description
何时使用/触发条件：AI Agent 何时自动激活该 skill
结构化的执行步骤
输出要求

简单的demo看下

---
name: demo-tailwindcss
description: 在项目中编写、重构、评审 TailwindCSS 代码时使用。
---

# demo TailwindCSS

## 何时使用

当任务涉及以下任一场景时使用本 skill：

- 编写或修改 React 组件的 `className`
- 把 CSS Modules / Less / 行内样式迁移到 Tailwind
- 修改 `tailwind.config.js`、新增包级 Tailwind 配置
- 新增或调整主题 token、颜色、字号、间距、圆角、阴影映射
- 审查 Tailwind 代码是否符合千问项目约定

## 先读这些文件

开始之前按这个顺序读取：

1. 
2.
3.

## 核心认知

- xx 是项目共享 Tailwind 配置入口，里面定义了 dark mode、content 扫描、plugin、variant 和 utility 约定。
- xx 是 Tailwind theme 的实际消费入口，暴露的是已经生成好的 token 映射。
- xx 是构建产物，不要直接手改。要改映射，请改 `src/adapters/tailwindCss.ts` 或 token 源，再重新构建主题。
- 业务样式优先复用语义 token，不要回退到硬编码颜色、字号、圆角和阴影。
- 本项目对 `hover:` 做了重定义，只在 `@media (hover: hover) and (pointer: fine)` 下生效。不要自己重复写这套媒体查询。

## 编写顺序

遇到一个样式需求时，按下面顺序决策：

1. 先找项目已有语义类
   - 例如 `text-primary`、`text-secondary`、`text-caption`
   - 例如 `bg-capsule`、`bg-option`、`bg-weaken`
   - 例如 `border-line-border`、`border-line-theme`
2. 再找 token 化尺寸类
   - 例如 `text-14`、`font-500`
   - 例如 `p-8px`、`gap-6px`
   - 例如 `rounded-8`、`shadow-2`
3. 再用项目自定义 variant / utility
   - 例如 `mac:`、`windows:`、`mobile:`、`hover:`
   - 例如 `scrollbar-thin`、`scrollbar-hide`
4. 最后才考虑任意值或 CSS Modules
   - 仅在 token 不存在、值确实动态、或需要复杂选择器时使用

## 颜色与主题规则

- 优先使用 theme token 映射出来的类，不直接写十六进制、`rgb()`、`hsl()`。
- 优先使用语义色，不要在业务组件里大量使用 Tailwind 默认调色板。
- 优先写 `text-primary`，不要默认写 `text-[var(--ty-text-primary)]`。
- 只有当 theme 里没有暴露目标 token，或者需要一次性动态值时，才用 `bg-[var(--ty-...)]` 这类任意值。
- 大多数场景不需要显式写 `dark:`。项目主题通过 CSS 变量切换亮暗态，优先让 token 自己完成主题切换。

## 字体与尺寸规则

- 字体使用主题映射：`font-text`、`font-text-latin`、`font-text-zh`、`font-text-ja`、`font-number`、`font-code`。
- 文本、间距、圆角、阴影优先使用 token 类，不要把 `14px`、`8px`、`12px`、阴影值直接硬编码进 class。
- 如果现有 token 无法表达，再决定是补 token，还是局部使用任意值。

## 平台与交互规则

- 平台差异优先使用共享 variant：`web:`、`desktop:`、`mac:`、`windows:`、`mobile:`、`not-mobile:`。
- 悬停交互统一使用项目里的 `hover:` variant，不要自己拼 `@media (hover: hover)`。
- 滚动条相关优先复用共享 utility：`scroll-bar`、`scrollbar-thin`、`sider-scrollbar`、`scrollbar-hide`、`scrollbar-default`。

## 配置修改规则

- 新增包级 `tailwind.config.js` 时，优先继承共享配置或至少复用同一套 theme/plugin/variant 约定，不要复制粘贴后自行漂移。
- 新增 theme token 时，优先修改 `src/adapters/tailwindCss.ts` 对应映射，而不是在业务侧用任意值绕过去。
- 新增 variant 或 utility 时，优先放到 `tailwind.config.js`，让全项目保持一致。
- 修改 `demo-theme` 主题产物后，需要重新构建：
  - `pnpm --filter demo-theme run build:theme`

## 避免这些做法

- 直接修改 `packages/demo-theme/dist/adapters/tailwindcss/theme.cjs`
- 在产品代码里硬编码 `#xxx`、`rgba(...)`、`12px`、`14px`
- 用 Tailwind 默认色板替代项目语义 token
- 大量使用 `text-[var(--ty-...)]`、`bg-[var(--ty-...)]` 代替现成语义类
- 通过字符串拼接动态生成 class，导致 Tailwind content 扫描不到
- 在单个业务包里偷偷新增一套不兼容的 Tailwind variant / utility

## 评审清单

- 是否先查过共享配置和 theme token 导出，而不是靠猜
- 是否优先使用了语义 token 类
- 是否避免了硬编码颜色、字号、圆角和阴影
- 是否正确使用平台 variant，而不是自行判断平台后切多套 class
- 是否避免了扫描不到的动态 className
- 如果改了 theme 生成逻辑，是否同时更新了源文件而非 dist 产物

## 输出要求

当你基于本 skill 产出修改方案时：

- 明确说明用了哪个共享配置或 token 来源
- 对任意值、CSS Modules、行内样式给出“为什么不能用 token 类”的理由
- 如果需要新增 token / variant / utility，优先给出“放到共享层”的方案

## 参考资料

- 速查和示例见 [reference.md](reference.md)

项目里的Agent Skills 体系理解