Placeholder System

占位符系统

ai-coding-ok 占位符系统完整参考——每个占位符、如何推断、如何替换。

---

概述

模板包含 {{占位符}}，安装时替换为项目特定值。AI 从用户的一句话描述中推断这些值。

模板：     "用 {{编程语言}} + {{框架}} 构建 {{项目名称}}"
用户说：   "一个个人记账工具"
AI 推断：  编程语言 = Python 3.12，框架 = FastAPI，项目名称 = 记账工具
结果：     "用 Python 3.12 + FastAPI 构建 记账工具"

---

中文占位符参考

项目标识

占位符	描述	示例	来源
{{项目名称}}	项目名（kebab-case）	记账工具	从描述推断
{{项目类型}}	完整项目类型描述	个人财务管理 CLI 工具	从描述推断
{{业务场景}}	项目做什么	记录每日花销，生成月度报表	从描述推断
{{用户规模}}	预期用户规模	单用户	从类型推断

技术栈

占位符	描述	示例	来源
{{编程语言}}	编程语言 + 版本	Python 3.12	从类型推断
{{框架}}	主要框架	FastAPI	从类型推断
{{数据库}}	数据库	SQLite	从规模推断
{{ORM}}	ORM 库	SQLAlchemy	从语言推断
{{测试框架}}	测试框架	pytest	从语言推断
{{包管理器}}	包管理器	pip	从语言推断

设计与架构

占位符	描述	示例
{{设计原则}}	设计原则	极简、实用、离线优先
{{架构模式}}	架构模式	MVC
{{核心功能}}	核心功能列表	记账、分类、月报
{{业务实体}}	业务实体	账单、分类、报表

日期

占位符	描述	示例
{{YYYY-MM-DD}}	当前日期	2026-07-14

Hooks

占位符	描述	示例
{{SOURCE_DIR_PATTERN}}	源码目录 grep 正则	^src/\|^tests/

---

推断逻辑

不确定时的默认选择

不确定…	默认…	原因
语言	Python 3.12	最通用
数据库	SQLite	最简单，无需服务器
框架（Web）	FastAPI	现代、文档好
框架（CLI）	Click	Python 标准
测试框架	pytest	Python 标准
ORM	SQLAlchemy	Python 标准
包管理器	pip	Python 标准

不确定时怎么办

AI 选更简单的方案并在 decisions-log.md 中记录为 ADR-001：

### ADR-001：选择 SQLite 而非 PostgreSQL

- **日期**：2026-07-14
- **状态**：✅ 已采纳

#### 背景
项目是个人记账工具。需要数据库。

#### 决策
SQLite。

#### 理由
单用户，无并发写入。SQLite 无需服务器设置。
PostgreSQL 在这个规模下增加了运维复杂度，没有收益。

用户可通过编辑 decisions-log.md 和 project-memory.md 后续覆盖。

---

替换过程

第 1 步：先替换标识

{{项目名称}} → 记账工具
{{项目类型}} → 个人财务管理工具

第 2 步：替换技术栈

{{编程语言}} → Python 3.12
{{框架}} → Click
{{数据库}} → SQLite

第 3 步：替换设计与约定

{{设计原则}} → 极简、实用、离线优先

第 4 步：替换日期

{{YYYY-MM-DD}} → 2026-07-14

第 5 步：替换源码目录

{{SOURCE_DIR_PATTERN}} → ^src/\\|^tests/

第 6 步：验证

运行 verify.sh 检查残留占位符。

---

占位符约束

约束	原因
英文：{{kebab-case}}	与 Markdown 和代码风格一致
中文：{{中文}}	中文用户自然
占位符名不含空格	边界模糊
每个占位符全局唯一	确保替换一致
不嵌套	避免 {{foo-{{bar}}}} 复杂性
日期始终 {{YYYY-MM-DD}}	全局统一日期格式

---

添加新占位符

当 ai-coding-ok 需要新占位符时：

1. 添加到模板文件中，同时更新 templates/en/ 和 templates/zh/
2. 更新 SKILL.md 第 6 步（占位符替换），包含新占位符
3. 更新 customize-prompt.md，在定制说明中包含新占位符
4. 更新 verify.sh，检查新占位符模式
5. 在此页面文档化

---

下一步

• 模板系统 — 模板和占位符如何协同工作
• 定制化指南 — 安装后如何定制
• 自定义模板 — 创建你自己的模板变体