AI Native 项目模板

这是一个 AI Native 项目的模板基座，用于快速搭建 AI 友好的工程结构。

注意：本 README 是给人类阅读的，与 AI 无关。在实际的 AI Native 项目中，不需要这个文件。

快速开始

方式一：迁移现有项目

如果你有一个现有的项目想要转换为 AI Native 结构：

# 1. 下载这个模板

# 2. 将你的项目代码复制到 projects 目录
# 单项目（复制到 projects/ 下，会保留原始文件夹名）：
cp -r /path/to/your-project ./projects/

# 多项目（前后端分离等）：
cp -r /path/to/frontend ./projects/
cp -r /path/to/backend ./projects/

# 3. 执行初始化命令
/an-init

AI 会自动分析 projects/ 下的每个子目录（每个视为一个独立工程），生成 background/ 文档和 convention/ 规范，并通过 AGENTS.md 路由给支持 AGENTS 的工具读取。 初始化时会主动询问是否使用子代理并行处理“可执行命令清单”和“背景扫描”。未启用子代理时，会在主流程中顺序执行同样脚本。

方式二：从零开始

如果你要从零开始一个新项目：

1. 复制模板到新项目目录
2. 直接告诉 AI 你的需求，比如：「帮我开发一个用户登录功能」
3. AI 会按照工作流，从需求分析到代码生成逐步引导你

流程：

/an-task 需求描述 → artifacts/{feature}/raw-input/ → requirements/ → design/ → tech-spec/ → implementation/ → projects/

AI 会在 artifacts/ 中创建任务产出目录，按阶段生成文档，最终在 projects/ 中生成代码。

目录结构

模板基座（初始化前）

ai-native-template/
├── AGENTS.md           # AI 入口文件
├── convention/         # 规范定义（由 AGENTS.md 路由加载）
│   ├── principles.md   # 核心原则
│   ├── workflow.md      # 工作流规范
│   └── document.md     # 文档编写规范
├── background/         # 背景知识（空，等待填充）
├── artifacts/          # 任务产出目录（空）
└── projects/          # 实际工程项目（空）

初始化后（执行 /an-init）

your-project/
├── AGENTS.md           # AI 入口文件（已填充项目背景）
├── convention/         # 规范（由 AGENTS.md 路由加载）
│   ├── workflow.md      # 工作流规范
│   ├── document.md     # 文档编写规范
│   ├── structure.md    # 目录结构规范（生成）
│   └── code-style.md   # 代码风格规范（生成）
├── background/
│   ├── AGENTS.md       # 背景目录说明
│   ├── product/        # 产品背景
│   │   └── overview.md
│   └── tech/           # 技术背景
│       └── stack.md
├── artifacts/          # 任务产出目录
│   └── AGENTS.md       # 产出目录说明
└── projects/          # 实际工程项目（每个子目录为一个工程）
    ├── frontend/       # 前端工程（示例）
    └── backend/        # 后端工程（示例）

可用命令

命令	用途
/an-init	迁移现有项目，分析 projects/ 下各工程的代码生成文档
/an-task	标准化流程实现 feature
/an-task-split	将大任务拆分为多个子任务
/an-recipes	探测并生成可执行命令清单
/an-refresh	根据实际代码反向更新 background 背景知识库
/an-eval	根据验收标准、测试证据、风险关闭和交付状态评价任务质量
/an-archive	将已完成的任务产出归档到 artifacts/archive/

从零开始不需要命令，直接告诉 AI 你的需求即可。

工作流

raw-input → requirements → design → tech-spec → implementation → testing → deployment

每个阶段 AI 会：

1. 生成对应文档
2. 等待用户确认
3. 进入下一阶段

可执行命令清单

初始化后可生成 .agents/recipes.json：

node .agents/skills/an-recipes/scripts/detect-recipes.mjs --root projects --write .agents/recipes.json

任务实现后，AI 优先从该文件选择最小验证命令，而不是临时猜测 npm test 或 pnpm build。

任务质量评价

L2/L3 任务完成后运行：

node .agents/skills/an-eval/scripts/evaluate-task.mjs artifacts/{YYYYMMDD}__{feature-name}

质量评价会输出 PASS、REVIEW 或 BLOCKED，分别表示“可交付”“建议复核”“不应关闭”。

核心原理

1. AI 是目标开发者：文档结构为 AI 设计，不是为人类
2. 有效上下文：上下文质量决定 AI 输出质量
3. 规范驱动开发：先定义规范，再由 AI 执行

相关入口

• AGENTS 入口文件 - AI 的入口文件
• 工程入口 - 实际工程项目