一个兼容主流 AI 编码工具的项目开发模板。解决每次新建项目都要重复告诉 AI 如何维护文档、遵循规范的问题。

工具	入口文件	机制
Claude Code	CLAUDE.md	@import 引用共享指令
Gemini CLI	GEMINI.md	@import 引用共享指令
Codex CLI	AGENTS.md	内联核心规范
OpenCode	AGENTS.md + CLAUDE.md	两个文件都读
Cursor	.cursorrules + AGENTS.md	规则文件 + fallback
Windsurf	.windsurfrules	独立规则文件
Aider	.aider.conf.yml	配置自动加载 AGENTS.md

# GitHub 模板方式
# 点击 "Use this template" 按钮

# 或直接克隆
git clone https://github.com/{{YOUR_USERNAME}}/ai-project-template.git my-project
cd my-project
rm -rf .git && git init

在所有文件中搜索并替换以下占位符：

占位符	说明	示例
{{PROJECT_NAME}}	项目名称	my-awesome-app
{{TECH_STACK}}	技术栈	Next.js 15 + TypeScript + Tailwind
{{DESCRIPTION}}	项目描述	一个在线协作白板应用

docs/ 目录下的模板文件有更多占位符（如 {{TARGET_USERS}}、{{FRAMEWORK}} 等），按需填写即可。

用任何支持的 AI 编码工具打开项目，AI 会自动读取对应的入口文件并遵循项目规范。

.
├── CLAUDE.md              # Claude Code 入口（@import 共享指令）
├── AGENTS.md              # Codex / OpenCode / Cursor 入口（内联规范）
├── GEMINI.md              # Gemini CLI 入口（@import 共享指令）
├── .cursorrules           # Cursor 兼容（指向 AGENTS.md）
├── .windsurfrules         # Windsurf 兼容（精简规则）
├── .aider.conf.yml        # Aider 兼容（自动加载 AGENTS.md）
├── .ai/
│   └── instructions.md    # 共享核心指令（行为规范 + 编码约定 + 工作流）
├── docs/
│   ├── PRD.md             # 产品需求文档模板
│   ├── ARCHITECTURE.md    # 架构设计文档模板
│   ├── FEATURE_PLAN.md    # 功能规划与路线图模板
│   ├── TODO.md            # 任务追踪模板
│   ├── CHANGELOG.md       # 变更日志模板
│   ├── SESSION_LOG.md     # 会话历史日志（跨会话上下文记忆）
│   └── DECISION_LOG.md    # 决策记录（需求/架构变化历史）
├── .gitignore
└── README.md              # 本文件（使用后请替换为项目自己的 README）

         CLAUDE.md ──@import──┐
                              ▼
         GEMINI.md ──@import──> .ai/instructions.md (共享指令源)
                              ▲
         AGENTS.md ──内联内容──┘
              │
    ┌─────────┴──────────┐
    ▼                    ▼
.cursorrules        .aider.conf.yml
.windsurfrules      (read: AGENTS.md)
(指向 AGENTS.md)

所有工具共同维护 ──> docs/ 目录下的活文档

核心理念：

• Claude Code 和 Gemini CLI 支持 @import，所以用薄入口文件引用共享指令
• Codex / OpenCode 不支持 @import，所以 AGENTS.md 内联核心内容
• 编辑器工具（Cursor / Windsurf / Aider）各有独立的薄兼容文件

文档	用途	更新时机
docs/PRD.md	产品需求	需求变更时
docs/ARCHITECTURE.md	架构设计	架构决策时
docs/FEATURE_PLAN.md	功能规划	功能规划/状态变化时
docs/TODO.md	任务追踪	每次工作会话开始和结束
docs/CHANGELOG.md	变更日志	每次有意义的变更后
docs/SESSION_LOG.md	会话历史	每次会话结束时追加摘要
docs/DECISION_LOG.md	决策记录	做出重要技术/产品决策时

1. 编码约定: 编辑 .ai/instructions.md 第 4 节，根据你的技术栈添加具体约定
2. 工作流: 编辑 .ai/instructions.md 第 5 节，调整分支策略和 PR 流程
3. 新增文档: 在 docs/ 中添加新模板，然后在 CLAUDE.md / GEMINI.md 中添加 @import，在 AGENTS.md 的第 7 节中添加引用
4. 工具专属配置: 如需 Claude 子 agent，创建 .claude/agents/ 目录；如需 OpenCode skill，创建 .opencode/skills/ 目录

本模板参考了以下社区实践：

• agents.md 规范 — "机器的 README" 标准
• KhazP/vibe-coding-prompt-template — 5 阶段 AI 开发工作流
• Keep a Changelog — 变更日志规范
• Conventional Commits — Git 提交规范

MIT