Custom Templates

自定义模板

如何扩展 ai-coding-ok 创建你自己的模板——适用于组织特定规范、合规要求或专门的项目类型。

---

何时创建自定义模板

场景	方法
团队有标准编码规范	安装后修改 coding-standards.md
组织有合规要求	添加 COMPLIANCE.md 模板
反复使用特定技术栈	为该技术栈创建 templates/ 变体
跨仓库共享规范	创建共享模板仓库

---

方法 1：安装后修改（最简单）

安装 ai-coding-ok 后直接编辑已安装文件：

# 编辑团队的编码规范
vim .github/agent/coding-standards.md

# 添加合规规则
echo "## SOC2 要求" >> .github/agent/memory/project-memory.md

# 提交变更
git add .github/agent/
git commit -m "chore: 为团队约定定制 ai-coding-ok"

优点： 简单，无需框架变更。
缺点： 每个项目需重复操作。变更可能与升级冲突。

---

方法 2：添加新模板文件

在 ai-coding-ok 仓库中添加自定义模板并在安装流程中引用：

第 1 步：创建模板

mkdir -p templates/en/my-org
mkdir -p templates/zh/my-org

创建 templates/zh/my-org/COMPLIANCE.md：

<!-- ai-coding-ok: v4.1.0 -->
# {{项目名称}} — 合规要求

## SOC2 控制项

| 控制项 | 要求 | 实现 |
|--------|------|------|
| 访问控制 | 所有接口需认证 | 由 {{框架}} 中间件强制执行 |
| 审计日志 | 所有数据变更记录 | 使用 {{数据库}} 审计表 |
| 加密 | 数据静态加密 | 使用 {{数据库}} 加密 |

第 2 步：更新安装流程

在 SKILL.md 中添加到安装文件列表和占位符替换清单。

第 3 步：更新安装脚本

在 install.sh 和 install.py 中添加新文件到复制列表。

第 4 步：更新 verify.sh

REQUIRED_FILES+=("my-org/COMPLIANCE.md")

---

方法 3：技术栈变体模板

为特定技术栈创建完整模板变体：

templates/
├── zh/
│   ├── default/          ← 标准模板
│   └── react-fastapi/    ← React + FastAPI 项目变体
│       ├── AGENTS.md
│       ├── .github/agent/coding-standards.md  ← JS + Python 规范
│       └── ...

---

方法 4：组织模板仓库

团队跨多个仓库共享模板：

git clone git@github.com:your-org/ai-coding-ok-templates.git

# 结构：
your-org-templates/
├── coding-standards.md      ← 覆盖默认
├── project-memory.md        ← 添加组织特定章节
├── COMPLIANCE.md            ← 自定义文件
└── install.sh               ← 包装脚本

---

模板文件规范

文件命名

• 根级文件使用 UPPER_CASE.md
• 子目录文件使用 kebab-case.md
• 匹配目标目录的现有命名规范

占位符命名

• 中文：{{中文名称}}（如 {{组织名称}}）
• 尽量复用现有占位符
• 文档化新占位符

版本标记

每个模板文件必须以以下内容开头：

<!-- ai-coding-ok: v4.1.0 -->

---

测试自定义模板

# 创建测试项目
mkdir /tmp/test-project
cd /tmp/test-project

# 用自定义模板运行安装
bash /path/to/your-templates/install.sh

# 验证
bash /path/to/ai-coding-ok/scripts/verify.sh

---

自定义模板检查清单

• 在 templates/en/ 和 templates/zh/ 中都创建了
• 尽量复用现有占位符
• 新占位符已文档化
• 第一行有版本标记
• 已添加到 SKILL.md 安装列表
• 已添加到 install.sh / install.py
• 已添加到 verify.sh 必需文件
• 已用全新安装测试
• 已用升级测试

---

下一步

• 模板系统 — 理解基础模板架构
• 占位符系统 — 占位符参考
• Contributing — 如何将模板贡献回 ai-coding-ok