Skip to content

Placeholder System

Jump to bottom
mark7766 edited this page Jul 14, 2026 · 2 revisions

Placeholder System

Complete reference for the ai-coding-ok placeholder system — every placeholder, how it's inferred, and how it's replaced.

Overview

Templates contain {{placeholders}} that are replaced with project-specific values during installation. The AI infers these values from the user's one-sentence project description.

Template:    "Building {{project-name}} with {{language}} + {{framework}}"
User says:   "A personal expense tracker"
AI infers:   project-name = expense-tracker, language = Python 3.12, framework = FastAPI
Result:      "Building expense-tracker with Python 3.12 + FastAPI"

English placeholder reference

Project identity

Placeholder Description Example Source
{{project-name}} Project name (kebab-case) expense-tracker Inferred from description
{{project-type}} Full project type description personal finance CLI tool Inferred from description
{{project-type-brief}} Short project type CLI tool Inferred from description
{{business-scenario}} What the project does record daily expenses, generate monthly reports Inferred from description
{{user-scale}} Expected user scale single user Inferred from type

Tech stack

Placeholder Description Example Source
{{language}} Programming language + version Python 3.12 Inferred from type
{{framework}} Main framework FastAPI Inferred from type
{{database}} Database SQLite Inferred from scale
{{orm}} ORM library SQLAlchemy Inferred from language
{{test-framework}} Test framework pytest Inferred from language
{{package-manager}} Package manager pip Inferred from language

Design & architecture

Placeholder Description Example Source
{{design-principles}} Design principles minimalist, practical, offline-first Inferred from type
{{architecture-pattern}} Architecture pattern MVC Inferred from type
{{core-features}} Core feature list expense recording, categorization, reports Inferred from description
{{business-entities}} Business domain entities Expense, Category, Report Inferred from description

Dates

Placeholder Description Example Source
{{YYYY-MM-DD}} Current date 2026-07-14 System date

Hooks

Placeholder Description Example Source
{{SOURCE_DIR_PATTERN}} grep regex for source dirs ^src/\|^tests/ User's answer

Chinese placeholder reference

Placeholder English equivalent Example
{{项目名称}} {{project-name}} 记账工具
{{项目类型}} {{project-type}} 个人财务管理工具
{{编程语言}} {{language}} Python 3.12
{{框架}} {{framework}} FastAPI
{{数据库}} {{database}} SQLite
{{ORM}} {{orm}} SQLAlchemy
{{测试框架}} {{test-framework}} pytest
{{包管理器}} {{package-manager}} pip
{{设计原则}} {{design-principles}} 极简、实用、离线优先
{{架构模式}} {{architecture-pattern}} MVC
{{核心功能}} {{core-features}} 记账、分类、月报
{{业务实体}} {{business-entities}} 账单、分类、报表
{{用户规模}} {{user-scale}} 单用户
{{YYYY-MM-DD}} {{YYYY-MM-DD}} 2026-07-14

Inference logic

How the AI infers values

The AI uses a decision tree based on the user's description:

User: "A personal expense tracker that records what I spend each day"
                    │
                    ▼
┌──────────────────────────────────────┐
│ Is it a web app, CLI, or mobile?     │
│ "tracker" → CLI tool                 │
└──────────────────────────────────────┘
                    │
                    ▼
┌──────────────────────────────────────┐
│ Single user or multi-user?           │
│ "personal" → single user             │
│ → SQLite (no server needed)          │
└──────────────────────────────────────┘
                    │
                    ▼
┌──────────────────────────────────────┐
│ Language?                            │
│ Personal tool → Python (simplicity)  │
│ → Python 3.12 + Click/argparse        │
└──────────────────────────────────────┘
                    │
                    ▼
┌──────────────────────────────────────┐
│ Design principles?                   │
│ Personal tool → minimalist, practical│
│ → offline-first, simple UI           │
└──────────────────────────────────────┘

Default choices (when uncertain)

If uncertain about... Default to... Reason
Language Python 3.12 Most general-purpose
Database SQLite Simplest, no server
Framework (web) FastAPI Modern, well-documented
Framework (CLI) Click Python standard
Test framework pytest Python standard
ORM SQLAlchemy Python standard
Package manager pip Python standard

When the AI is uncertain

The AI picks the simpler option and records the decision as ADR-001 in decisions-log.md:

### ADR-001: Chose SQLite over PostgreSQL

- **Date**: 2026-07-14
- **Status**: ✅ Accepted

#### Background
Project is a personal expense tracker. Need a database.

#### Decision
SQLite.

#### Rationale
Single-user, no concurrent writes. SQLite eliminates server setup.
PostgreSQL would add operational complexity with no benefit at this scale.

#### Impact
Database is a single file. No Docker/postgres service needed.

The user can override later by editing decisions-log.md and project-memory.md.

Replacement process

Step 1: Identity first

Replace project name and type first — these are used in other placeholders:

{{project-name}} → expense-tracker
{{project-type}} → personal finance tool

Step 2: Tech stack

Replace all tech stack placeholders:

{{language}} → Python 3.12
{{framework}} → Click
{{database}} → SQLite

Step 3: Design and conventions

{{design-principles}} → minimalist, practical, offline-first

Step 4: Dates

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

Step 5: Source directory

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

Step 6: Verify

Run verify.sh to check for leftover placeholders.

Placeholder constraints

Constraint Reason
English: {{kebab-case}} Consistent with Markdown and code conventions
Chinese: {{中文}} Natural for Chinese-speaking users
No spaces in placeholder names Ambiguous boundaries
Each placeholder unique across all files Consistent replacement
No nested placeholders Avoid {{foo-{{bar}}}} complexity
Dates always {{YYYY-MM-DD}} Single date format across all files

Files that contain placeholders

All 19 template files contain placeholders. The distribution:

File Placeholder count (approx.)
AGENTS.md 12-15
.github/agent/memory/project-memory.md 12-15
.github/agent/system-prompt.md 8-10
.github/copilot-instructions.md 8-10
.github/agent/coding-standards.md 6-8
.github/project-metadata.yml 8-10
.github/agent/workflows.md 5-7
.github/workflows/ci.yml 3-5
.github/agent/prompt-templates.md 3-5
.github/agent/memory/decisions-log.md 2-3
.github/agent/memory/task-history.md 2-3
CLAUDE.md 1-2
.claude/settings.local.json 1 (SOURCE_DIR_PATTERN)
.cursor/rules/ai-coding-ok.mdc 1-2
.github/PULL_REQUEST_TEMPLATE.md 1-2
.github/ISSUE_TEMPLATE/* 1-2

Adding a new placeholder

When ai-coding-ok needs a new placeholder:

  1. Add to the template files in both templates/en/ and templates/zh/
  2. Update SKILL.md Step 6 (placeholder replacement) to include the new placeholder
  3. Update customize-prompt.md to include the new placeholder in the customization instructions
  4. Update verify.sh to check for the new placeholder pattern
  5. Document in this page

Next steps

🧠 ai-coding-ok — AI 编程的 PDCA 记忆闭环。
GitHub · Issues · MIT License

🧠 ai-coding-ok

🏠 首页

📖 快速上手

🧠 核心概念

📘 使用指南

🏗️ 架构

🔧 高级

📋 参考

GitHub 仓库

Clone this wiki locally