AI Coding Flow

A modular system prompt framework for AI coding assistants — with persistent memory, structured methodology, and verifiable outputs.

繁體中文版 | English

English

The Problem

Every time you start a new AI coding session, you lose everything — the architecture decisions you discussed, the bugs you found, the conventions you agreed on. Your AI assistant has amnesia.

Most AI tools offer some form of memory, but it's locked inside their platform. Switch from Claude Code to Gemini CLI? Start over. Want to version-control your AI's knowledge? Can't.

The Solution

AI Coding Flow gives your AI:

🧠 Memory that lives in Git — AI-Brain is just Markdown files in a Git repo. Version-controlled, diffable, greppable. You own your data.
🔌 Modular Skills — 12 self-contained behavioral modules. Enable what you need, customize what you want, create your own.
🏗️ Structured methodology — Enforces artifact-gated DDD → BDD → TDD with Cucumber feature extraction and rule traceability.
✅ Verifiable outputs — Code and config changes end with a verification stamp showing what was checked and what was skipped.
📚 Cross-project learning — Common AI-Brain accumulates wisdom across all your projects. Fix a Docker DNS issue once, every project knows about it.
📦 No runtime service dependencies — No database, no server, no API keys. Optional helper features use standard local CLI tools such as python3 and jq.

How It's Different

Approach	Platform-locked?	Version-controlled?	Cross-tool?	Survives tool migration?
ChatGPT Memory	✅	❌	❌	❌
Claude Projects	✅	❌	❌	❌
CLAUDE.md / GEMINI.md	❌	✅	❌ (tool-specific)	❌
AI Coding Flow	❌	✅	✅	✅

Architecture

v5.0 uses a modular Skill architecture. The system prompt is a thin orchestrator that delegates specialized behavior to self-contained Skills.

┌─────────────────────────────────────────────┐
│  System Prompt (system-prompt-v5.md)        │  ← Source orchestrator
│  Tool wrappers (CLAUDE.md / AGENTS.md)      │  ← Tool-specific entrypoints
│  Core identity, response principles,        │
│  skill loading rules                        │
├─────────────────────────────────────────────┤
│  Skills (skills/*/SKILL.md)                 │  ← Modular behavior
│  12 self-contained modules with             │
│  triggers, rules, and authority levels      │
├─────────────────────────────────────────────┤
│  AI-Brain templates (_common/ + _example/)  │  ← Persistent memory templates
│  Git-versioned Markdown files               │
│  Used by project AI-Brain + common AI-Brain │
└─────────────────────────────────────────────┘

Skills Reference

Skill	Type	Purpose
`warm-persona`	Always Active	Tone, communication style, dynamic role adaptation
`response-protocol`	Always Active	Thinking protocol, response priority, action authority, decision dimensions
`ai-brain`	Always Active	Long-term memory system, AI-Brain loading procedure
`ddd-bdd-tdd`	Conditional	Structured development: DDD artifacts → BDD specs → Cucumber features → TDD implementation
`product-ui-designer`	Conditional	Product UI design: visual hierarchy, page patterns, component recipes, frontend polish
`code-verification`	Conditional	Verification loop, escalation protocol, response ending stamps
`tech-defaults`	Conditional	Default tech stack and technology selection guidance
`git-workflow`	Conditional	Commit conventions, branch naming, PR standards
`conversation-logger`	Conditional	Observe and record recurring patterns
`skill-extractor`	Conditional	Analyze patterns and propose new Skills
`brain-distiller`	Conditional	Distill bloated AI-Brain files: cluster, merge, archive stale entries
`prompt-engineer`	Conditional	Diagnose and fix rule violations in Skills

Always Active Skills load in every conversation. Conditional Skills activate only when their trigger conditions are met (e.g., ddd-bdd-tdd activates for new features, git-workflow activates when committing).

Project Structure

ai-coding-flow/
├── README.md
├── LICENSE
├── .gitignore
├── setup.sh                        ← Multi-tool installer (Claude / Gemini / Codex)
├── system-prompt-v5.md              ← Core system prompt source (orchestrator)
├── CLAUDE.md                        ← Claude Code entrypoint with Claude-specific rules and hook guidance
├── AGENTS.md                        ← Codex-specific prompt overlay
├── claude/
│   └── settings.json                ← Claude Code settings template (hooks + optional statusLine)
├── gemini/
│   └── settings.json                ← Gemini CLI hook template (2 hooks)
├── scripts/
│   ├── brain-loader.sh              ← SessionStart hook (AI-Brain Map injection)
│   ├── brain-gate.sh                ← PreToolUse hook (forces text response before tools)
│   ├── no-coauthor-guard.sh         ← PreToolUse hook (blocks Co-Authored-By in commits)
│   ├── journal-reminder.sh          ← PreToolUse hook (reminds to update journal.md)
│   └── statusline.sh               ← Status line (model, context bar, diff stats, branch)
├── _common/                         ← Common AI-Brain templates
│   ├── _catalog.json                ← Category index (auto-managed by AI)
│   ├── SCHEMA.md                    ← Data structure reference
│   ├── preferences.md               ← Personal preferences template
│   ├── troubleshooting.md           ← Cross-project troubleshooting template
│   ├── toolchain.md                 ← Toolchain experience template
│   ├── conversation-patterns.md     ← Conversation pattern log (skill-owned)
│   ├── skill-experience.md          ← Skill tuning and pitfall log (skill-owned)
│   └── prompt-violations.md         ← Rule violation tracker (skill-owned)
├── _example/                        ← Example AI-Brain folder (reference for new projects)
│   ├── architecture_decisions.md
│   ├── todo.md
│   ├── known_issues.md
│   └── journal.md
└── skills/                          ← Modular Skills (v5.0)
    ├── warm-persona/SKILL.md
    ├── response-protocol/SKILL.md
    ├── ai-brain/SKILL.md
    ├── ddd-bdd-tdd/SKILL.md
    ├── product-ui-designer/SKILL.md
    ├── code-verification/SKILL.md
    ├── git-workflow/SKILL.md
    ├── tech-defaults/SKILL.md
    ├── conversation-logger/SKILL.md
    ├── brain-distiller/SKILL.md
    ├── skill-extractor/SKILL.md
    └── prompt-engineer/SKILL.md

Quick Start

1. Clone the framework

git clone https://github.com/JTH58/ai-coding-flow.git

2. Set up AI-Brain (your private memory)

AI-Brain is a separate repo that lives alongside your project directories. The AI reads and writes to it during work.

# Create and initialize your AI-Brain repo
mkdir -p ~/Documents/GitHub/ai-brain
cd ~/Documents/GitHub/ai-brain
git init

# Copy templates from the framework
cp -r ~/Documents/GitHub/ai-coding-flow/_common .
cp -r ~/Documents/GitHub/ai-coding-flow/_example .

git add -A && git commit -m "init: AI-Brain"

Recommended: Push to a private GitHub repo to back up your AI-Brain and enable cross-machine access.
# Create a private repo on GitHub first, then:
git remote add origin https://github.com/<your-username>/ai-brain.git
git push -u origin main

Your directory structure should look like:

~/Documents/GitHub/
├── ai-coding-flow/      ← This framework (public)
├── ai-brain/            ← Your AI-Brain data (private)
│   ├── _common/         ← Shared across all projects
│   └── _example/        ← Templates for new projects
└── my-project/          ← Your code project

The AI automatically derives the AI-Brain path from your working directory: $(dirname "$PWD")/ai-brain/. As long as ai-brain/ sits beside your project folders, it just works.

3. Apply to your AI tool

Run the unified installer and select your tool:

cd ~/Documents/GitHub/ai-coding-flow
./setup.sh

The installer supports Claude Code, Gemini CLI, and OpenAI Codex. You can set up one tool or all three at once.

Before you continue: setup.sh modifies files under ~/.claude/, ~/.gemini/, and/or ~/.codex/. It now shows a confirmation prompt before making changes. If you already have custom global config in those directories, review or back it up first.

Optional local prerequisites: python3 is needed for automatic settings.json merge and Claude statusLine installation. jq is needed only for scripts/statusline.sh.

Claude Code (recommended — full Skill support)

Claude Code natively supports the modular Skill architecture via CLAUDE.md + custom Skills.

What setup.sh does (option 1):

Symlinks all Skills to ~/.claude/skills/
Symlinks CLAUDE.md to ~/.claude/CLAUDE.md
Symlinks all scripts to ~/.claude/scripts/
Merges hooks into ~/.claude/settings.json (idempotent)
Optionally installs statusLine into ~/.claude/settings.json

Edits to project files take effect immediately — no manual sync needed.

Claude Code reads CLAUDE.md hierarchically: global (~/.claude/CLAUDE.md) applies everywhere, project-level (.claude/CLAUDE.md) adds project-specific context. Skills in ~/.claude/skills/ are available globally.

What the hooks do:

brain-loader.sh (SessionStart) — Injects an AI-Brain Map (~20 lines): file paths, descriptions, and entry counts. No full file contents are injected. The AI reads the user's message, selects relevant files, and reads them on demand (directly if < 15 entries, via Explore sub-agent if ≥ 15). The === AI BRAIN === marker tells the AI to skip manual loading.
brain-gate.sh (PreToolUse) — Blocks the first tool call after AI-Brain loading, forcing the AI to produce a text response first. This prevents the AI from silently jumping into code changes before acknowledging context. Subsequent tool calls pass through normally.
no-coauthor-guard.sh (PreToolUse:Bash) — Blocks git commit commands that contain Co-Authored-By trailers, enforcing the git-workflow Skill rule.
journal-reminder.sh (PreToolUse:Edit|Write|NotebookEdit) — Non-blocking reminder to update journal.md in the same response when editing project files. Skips AI-Brain files. Works with the Stop hook (hard block) as a two-layer defense.

Status line:

statusline.sh — Displays a 3-line status bar: line 1 shows diff stats + branch + path, line 2 shows model + context remaining, line 3 shows week and 5-hour usage windows.

If no AI-Brain repo exists next to your project, the AI-Brain hooks silently do nothing.

Updating: When the framework releases a new version, just pull — symlinks pick up changes automatically:

cd ~/Documents/GitHub/ai-coding-flow && git pull

Gemini CLI

What setup.sh does (option 2):

Generates a bundled prompt at ~/.gemini/GEMINI.md (system-prompt + essential Skills)
Symlinks brain-loader.sh and brain-gate.sh to ~/.gemini/scripts/
Merges hooks into ~/.gemini/settings.json

The bundled prompt includes response-protocol + ai-brain + code-verification + product-ui-designer — the recommended minimum for structured behavior and stronger product UI output.

Note: Gemini CLI hook format may differ from the template. Test with gemini and adjust ~/.gemini/settings.json if needed.

Manual alternative (per-project):

mkdir -p .gemini
cp ~/Documents/GitHub/ai-coding-flow/system-prompt-v5.md .gemini/system.md

For full Skill functionality, append relevant skills/*/SKILL.md contents to the prompt file.

OpenAI Codex

What setup.sh does (option 3):

Copies AGENTS.md to ~/.codex/AGENTS.md
Symlinks all scripts to ~/.codex/scripts/
Symlinks all project Skills to ~/.codex/skills/

Codex does not support Claude-style lifecycle hooks, but it can use the linked Skills in ~/.codex/skills/. In practice, AGENTS.md is the Codex-specific prompt layer and the linked Skills are available for reuse and trigger-based behavior inside Codex.

Manual alternative (per-project):

cp ~/Documents/GitHub/ai-coding-flow/AGENTS.md AGENTS.md

For reusable Skill support, also copy or symlink the relevant skills/ folders into ~/.codex/skills/.

Other AI Tools

The framework works with any AI tool that accepts custom system prompts:

Copy the content of system-prompt-v5.md into your tool's system prompt field
For full methodology, append the contents of relevant skills/*/SKILL.md files
Ensure the AI has shell access to read/write AI-Brain files

The system prompt is written in English by design. In practice, English instructions tend to produce better compliance and more compact prompts for current coding models.

How It Works

AI-Brain: Memory That Lives in Git

Your AI reads and writes to plain Markdown files — no proprietary format, no platform lock-in.

~/Documents/GitHub/ai-brain/
├── _common/                 ← Shared across ALL projects
│   ├── preferences.md       ← "I prefer Prisma over Drizzle"
│   └── troubleshooting.md   ← "Docker DNS fix: use host.docker.internal"
├── my-web-app/              ← Project-specific memory (auto-created)
│   ├── architecture_decisions.md  ← "Next.js 15 + Tailwind + Prisma"
│   └── known_issues.md      ← "SSR hydration bug on /dashboard"
└── my-mobile-app/
    └── ...

Because it's Git:

git log shows when decisions were made and why
git diff shows what changed between sessions
git branch lets you experiment with different architectural approaches
Team members can share project knowledge via pull requests

Artifact-Gated DDD → BDD → TDD

Activated automatically for new features and complex logic (via the ddd-bdd-tdd skill):

1. DDD Phase → AI writes docs/ddd/<feature-name>.DDD.md
                Defines contexts, entities, events, and INV/BR/OR rule IDs
                You confirm ✓

2. BDD Phase → AI writes docs/bdd/<feature-name>.bdd.md
                Designs Given-When-Then scenarios with @rule:<RULE-ID> tags
                You confirm ✓

3. Feature Extraction → AI runs the project extraction script
                       Generates test/features/<feature-name>.feature

4. TDD Phase → AI writes unit tests under tests/unit/...
                Adds Cucumber step definitions, then implements

5. CI Verification → Unit tests, BDD scenarios, and rule coverage pass
                    Code delivered ✓

Each phase requires your explicit approval before proceeding. Simple bug fixes and config changes skip this entirely.

Before writing tests, the AI studies 2+ similar implementations in your codebase to match existing patterns and reuse existing utilities. If the project already has nyc cucumber-js, it is used for BDD reverse coverage; otherwise the AI follows the existing project test commands and reports missing extraction or BDD runner gaps instead of adding dependencies silently.

Verification Stamps

Code responses end with a verification-phase stamp (via the code-verification skill):

Stamp	Meaning
`📌 DDD Complete — Awaiting Confirmation`	Domain model ready for review
`📌 BDD Complete — Awaiting Confirmation`	Scenarios ready for review
`✅ Tests: [X/X] \| Build: [Command]`	Code delivered with passing tests
`✅ Build Verified: [Command]`	Code delivered, build confirmed
`⚠️ Verification Skipped: [Reason]`	Discussion only, no code

If the same error persists after 3 attempts, the AI stops, documents what was tried, and proposes a fundamentally different approach (Escalation Protocol).

Customization Guide

This framework is designed to be forked and personalized. Here's what to change and where:

Persona & Language

What to change	File	Default
How AI addresses you	`system-prompt-v5.md` or `CLAUDE.md` → Core Identity table	`"dear" (親愛的)`
Output language	`system-prompt-v5.md` or `CLAUDE.md` → Core Identity table	`Traditional Chinese (繁體中文)`
Personality tone	`system-prompt-v5.md` or `CLAUDE.md` → Core Identity table	`Opinionated Neutrality`
Communication style	`skills/warm-persona/SKILL.md`	Warm, Pyramid Principle

Tech Stack Defaults

Edit skills/tech-defaults/SKILL.md to change default technology choices (used when no project-specific stack is defined).

Tip: These are just defaults. Each project's architecture_decisions.md in AI-Brain overrides them. You don't need to modify Skills for per-project changes.

BDD Keywords

Edit skills/ddd-bdd-tdd/SKILL.md to change Gherkin keywords (default: 假如 / 當 / 那麼 / 而且).

Product UI Design

Edit skills/product-ui-designer/SKILL.md and its references/ files to tune visual design rules, component recipes, page patterns, and final polish checks.

Git Conventions

Edit skills/git-workflow/SKILL.md to change commit message format, branch naming, and PR standards.

Creating Custom Skills

You can create your own Skills by adding a SKILL.md file in a new subdirectory under skills/:

skills/
└── my-custom-skill/
    └── SKILL.md

Each SKILL.md needs a YAML front matter with name and description (including trigger conditions), followed by the skill's rules and procedures. See existing Skills for reference.

Compatibility

This framework is primarily designed for Claude Code with full Skill support. It also works with other AI tools with varying levels of functionality:

Tool	System Prompt	Skills	AI-Brain	Methodology
Claude Code	✅	✅ Native	✅	✅ Full
Gemini CLI	✅	⚠️ Bundled/manual	✅	⚠️ Prompt-driven
OpenAI Codex	✅	✅ AGENTS.md + linked Skills	✅	⚠️ Prompt-driven
Other CLI tools	✅	⚠️ Manual append	✅	⚠️ Varies by tool

Verification stamp compliance varies by model and tool integration. Claude Code is the primary target; Gemini CLI, Codex, and other tools depend more heavily on prompt adherence and local setup quality. If a rule is not followed consistently, please open an issue with the tool, model, and setup you used.

Contributing

Contributions are welcome! Feel free to:

Open issues for bugs, suggestions, or rule compliance problems
Submit PRs for new Skills, improvements, or translations
Share your custom Skills with the community

License

MIT

繁體中文

問題

每次啟動新的 AI 編程對話，一切都會遺失 — 討論過的架構決策、發現的 Bug、約定的慣例。你的 AI 助手有失憶症。

大多數 AI 工具提供某種形式的記憶功能，但都鎖在自家平台裡。從 Claude Code 換到 Gemini CLI？重新開始。想版本控制 AI 的知識？做不到。

解決方案

AI Coding Flow 讓你的 AI 擁有：

🧠 活在 Git 裡的記憶 — AI-Brain 只是 Git repo 中的 Markdown 檔案。可版控、可 diff、可 grep。資料完全屬於你。
🔌 模組化 Skills — 12 個獨立的行為模組。啟用你需要的，自訂你想改的，建立你自己的。
🏗️ 結構化方法論 — 強制執行 artifact-gated DDD → BDD → TDD，包含 Cucumber feature 抽取與規則追溯。
✅ 可驗證的輸出 — 涉及程式碼或設定變更時，回應結尾會附上驗證戳記，說明驗證了什麼、跳過了什麼。
📚 跨專案學習 — Common AI-Brain 在所有專案間積累智慧。修過一次 Docker DNS 問題，所有專案都知道解法。
📦 無執行期服務依賴 — 不需要資料庫、不需要伺服器、不需要 API key。可選的輔助功能只依賴本機常見 CLI，如 python3 與 jq。

有何不同

方案	平台綁定？	可版控？	跨工具？	換工具後保留？
ChatGPT Memory	✅	❌	❌	❌
Claude Projects	✅	❌	❌	❌
CLAUDE.md / GEMINI.md	❌	✅	❌（工具專用）	❌
AI Coding Flow	❌	✅	✅	✅

架構

v5.0 採用模組化 Skill 架構。系統提示詞是精簡的協調者，將專業行為委派給獨立的 Skill。

┌─────────────────────────────────────────────┐
│  系統提示詞 (system-prompt-v5.md)            │  ← 原始協調者
│  工具入口 (CLAUDE.md / AGENTS.md)            │  ← 工具專用入口
│  核心身份、回應原則、Skill 載入規則           │
├─────────────────────────────────────────────┤
│  Skills (skills/*/SKILL.md)                 │  ← 模組化行為
│  12 個獨立模組，各有觸發條件、規則、授權等級  │
├─────────────────────────────────────────────┤
│  AI-Brain 模板 (_common/ + _example/)       │  ← 持久記憶模板
│  Git 版控的 Markdown 檔案                    │
│  用於 project AI-Brain 與 common AI-Brain   │
└─────────────────────────────────────────────┘

Skills 總覽

Skill	類型	用途
`warm-persona`	常駐	語氣、溝通風格、動態角色適應
`response-protocol`	常駐	思考協議、回應優先順序、行動授權、決策維度
`ai-brain`	常駐	長期記憶系統、AI-Brain 載入程序
`ddd-bdd-tdd`	條件觸發	結構化開發：DDD artifact → BDD 規格 → Cucumber feature → TDD 實作
`product-ui-designer`	條件觸發	產品 UI 設計：視覺層級、頁面模式、元件配方、前端 polish
`code-verification`	條件觸發	驗證迴圈、升級協議、回應結尾戳記
`tech-defaults`	條件觸發	預設技術棧與選型指南
`git-workflow`	條件觸發	提交約定、分支命名、PR 標準
`conversation-logger`	條件觸發	觀察並記錄重複模式
`skill-extractor`	條件觸發	分析模式並提議新 Skill
`brain-distiller`	條件觸發	蒸餾膨脹的 AI-Brain 檔案：聚類、合併、歸檔過期條目
`prompt-engineer`	條件觸發	診斷並修復 Skill 規則違反

常駐 Skill 在每次對話中載入。條件觸發 Skill 僅在觸發條件成立時啟動（如 ddd-bdd-tdd 在新功能開發時啟動，git-workflow 在提交時啟動）。

專案結構

ai-coding-flow/
├── README.md
├── LICENSE
├── .gitignore
├── setup.sh                        ← 多工具安裝腳本（Claude / Gemini / Codex）
├── system-prompt-v5.md              ← 核心系統提示詞原始檔（協調者）
├── CLAUDE.md                        ← Claude Code 入口，包含 Claude 專用規則與 hook 說明
├── AGENTS.md                        ← Codex 專用提示詞覆蓋層
├── claude/
│   └── settings.json                ← Claude Code 設定模板（hooks + 可選 statusLine）
├── gemini/
│   └── settings.json                ← Gemini CLI hook 模板（2 個 hook）
├── scripts/
│   ├── brain-loader.sh              ← SessionStart hook（AI-Brain Map 注入到 context）
│   ├── brain-gate.sh                ← PreToolUse hook（強制先回應再用工具）
│   ├── no-coauthor-guard.sh         ← PreToolUse hook（攔截 Co-Authored-By 提交）
│   ├── journal-reminder.sh          ← PreToolUse hook（提醒更新 journal.md）
│   └── statusline.sh               ← 狀態列（模型、context 進度條、diff 統計、分支）
├── _common/                         ← Common AI-Brain 模板
│   ├── _catalog.json                ← 分類索引（AI 自動管理）
│   ├── SCHEMA.md                    ← 資料結構參考
│   ├── preferences.md               ← 個人偏好模板
│   ├── troubleshooting.md           ← 跨專案踩坑紀錄模板
│   ├── toolchain.md                 ← 工具鏈經驗模板
│   ├── conversation-patterns.md     ← 會話模式日誌（Skill 專用）
│   ├── skill-experience.md          ← Skill 調校與踩坑日誌（Skill 專用）
│   └── prompt-violations.md         ← 規則違反追蹤（Skill 專用）
├── _example/                        ← 範例 AI-Brain 資料夾（新專案參考用）
│   ├── architecture_decisions.md
│   ├── todo.md
│   ├── known_issues.md
│   └── journal.md
└── skills/                          ← 模組化 Skills (v5.0)
    ├── warm-persona/SKILL.md
    ├── response-protocol/SKILL.md
    ├── ai-brain/SKILL.md
    ├── ddd-bdd-tdd/SKILL.md
    ├── product-ui-designer/SKILL.md
    ├── code-verification/SKILL.md
    ├── git-workflow/SKILL.md
    ├── tech-defaults/SKILL.md
    ├── conversation-logger/SKILL.md
    ├── brain-distiller/SKILL.md
    ├── skill-extractor/SKILL.md
    └── prompt-engineer/SKILL.md

快速開始

1. Clone 框架

git clone https://github.com/JTH58/ai-coding-flow.git

2. 設定 AI-Brain（你的私有記憶）

AI-Brain 是獨立的 repo，與你的專案目錄並排放置。AI 工作時會自動讀寫。

# 建立並初始化你的 AI-Brain repo
mkdir -p ~/Documents/GitHub/ai-brain
cd ~/Documents/GitHub/ai-brain
git init

# 從框架複製模板
cp -r ~/Documents/GitHub/ai-coding-flow/_common .
cp -r ~/Documents/GitHub/ai-coding-flow/_example .

git add -A && git commit -m "init: AI-Brain"

建議： 推送到私有 GitHub repo，備份你的 AI-Brain 並支援跨機器存取。
# 先在 GitHub 建立私有 repo，然後：
git remote add origin https://github.com/<your-username>/ai-brain.git
git push -u origin main

你的目錄結構應該像這樣：

~/Documents/GitHub/
├── ai-coding-flow/      ← 本框架（公開）
├── ai-brain/            ← 你的 AI-Brain 資料（私有）
│   ├── _common/         ← 所有專案共享
│   └── _example/        ← 新專案的模板
└── my-project/          ← 你的程式碼專案

AI 會從你的工作目錄自動推導 AI-Brain 路徑：$(dirname "$PWD")/ai-brain/。只要 ai-brain/ 和你的專案資料夾放在同一層，就能自動運作。

3. 套用到你的 AI 工具

執行統一安裝腳本並選擇你的工具：

cd ~/Documents/GitHub/ai-coding-flow
./setup.sh

安裝腳本支援 Claude Code、Gemini CLI 和 OpenAI Codex。你可以一次設定一個工具或全部一起。

執行前請注意： setup.sh 會修改 ~/.claude/、~/.gemini/ 與/或 ~/.codex/ 下的檔案。腳本現在會在實際寫入前先顯示確認提示。若你已經有自訂的全域設定，請先檢查或備份。

可選本機前置條件： 自動合併 settings.json 與安裝 Claude statusLine 需要 python3。scripts/statusline.sh 只在你要使用狀態列時才需要 jq。

Claude Code（推薦 — 完整 Skill 支援）

Claude Code 透過 CLAUDE.md + 自訂 Skills 原生支援模組化 Skill 架構。

setup.sh 做了什麼（選項 1）：

將所有 Skills symlink 到 ~/.claude/skills/
將 CLAUDE.md symlink 到 ~/.claude/CLAUDE.md
將所有腳本 symlink 到 ~/.claude/scripts/
將 hooks 合併到 ~/.claude/settings.json（冪等操作）
可選擇是否安裝 statusLine 到 ~/.claude/settings.json

編輯專案檔後立即生效，不需手動同步。

Claude Code 階層式讀取 CLAUDE.md：全域（~/.claude/CLAUDE.md）適用所有專案，專案級（.claude/CLAUDE.md）添加專案上下文。~/.claude/skills/ 中的 Skills 全域可用。

Hook 做了什麼：

brain-loader.sh（SessionStart） — 注入 AI-Brain Map（約 20 行）：檔案路徑、描述、條目數。不注入完整檔案內容。AI 讀取使用者訊息後選擇相關檔案按需讀取（< 15 條直接讀、≥ 15 條派 Explore sub-agent 蒸餾）。=== AI BRAIN === 標記告訴 AI 跳過手動載入。
brain-gate.sh（PreToolUse） — 在 AI-Brain 載入後攔截第一個 tool call，強制 AI 先產生文字回應。這可防止 AI 在未確認 context 的情況下直接跳入修改程式碼。後續 tool call 正常放行。
no-coauthor-guard.sh（PreToolUse:Bash） — 攔截含有 Co-Authored-By 的 git commit 命令，強制遵守 git-workflow Skill 規則。
journal-reminder.sh（PreToolUse:Edit|Write|NotebookEdit） — 編輯專案檔時非阻斷式提醒更新 journal.md，跳過 AI-Brain 檔案。與 Stop hook（硬攔截）形成雙層防線。

狀態列：

statusline.sh — 顯示 3 行狀態列：第 1 行為 diff 統計 + branch + path，第 2 行為 model + context remaining，第 3 行為 week 與 5-hour usage 視窗。

若專案旁邊沒有 AI-Brain repo，AI-Brain hook 靜默不做任何事。

更新： 框架發布新版本時，拉取即可 — symlink 會自動反映變更：

cd ~/Documents/GitHub/ai-coding-flow && git pull

Gemini CLI

setup.sh 做了什麼（選項 2）：

在 ~/.gemini/GEMINI.md 生成打包提示詞（系統提示詞 + 必要 Skills）
將 brain-loader.sh 和 brain-gate.sh symlink 到 ~/.gemini/scripts/
將 hooks 合併到 ~/.gemini/settings.json

打包的提示詞包含 response-protocol + ai-brain + code-verification + product-ui-designer — 結構化行為與更強產品 UI 輸出的建議最小組合。

備註： Gemini CLI 的 hook 格式可能與模板不同。使用 gemini 測試後視需要調整 ~/.gemini/settings.json。

手動替代方案（單一專案）：

mkdir -p .gemini
cp ~/Documents/GitHub/ai-coding-flow/system-prompt-v5.md .gemini/system.md

如需完整 Skill 功能，將相關 skills/*/SKILL.md 內容附加到提示詞檔案。

OpenAI Codex

setup.sh 做了什麼（選項 3）：

複製 AGENTS.md 到 ~/.codex/AGENTS.md
將所有腳本 symlink 到 ~/.codex/scripts/
將專案 Skills 全部 symlink 到 ~/.codex/skills/

Codex 不支援 Claude 式生命週期 hook，但可以使用 symlink 到 ~/.codex/skills/ 的 Skills。實務上 AGENTS.md 是 Codex 專用提示詞層，而 linked Skills 可在 Codex 內被重用，並依環境支援觸發相應行為。

手動替代方案（單一專案）：

cp ~/Documents/GitHub/ai-coding-flow/AGENTS.md AGENTS.md

如需可重用的 Skill 支援，也請將相關 skills/ 資料夾複製或 symlink 到 ~/.codex/skills/。

其他 AI 工具

本框架適用於任何接受自訂系統提示詞的 AI 工具：

將 system-prompt-v5.md 的內容複製到工具的系統提示詞欄位
如需完整方法論，附加相關 skills/*/SKILL.md 的內容
確保 AI 有 Shell 存取權限以讀寫 AI-Brain 檔案

提示詞刻意使用全英文。以目前的 coding model 來看，英文指令通常有較好的遵從率，提示詞也較精簡。

運作原理

AI-Brain：活在 Git 裡的記憶

AI 讀寫純 Markdown 檔案 — 沒有專有格式，沒有平台鎖定。

~/Documents/GitHub/ai-brain/
├── _common/                 ← 所有專案共享
│   ├── preferences.md       ← 「我偏好 Prisma 而非 Drizzle」
│   └── troubleshooting.md   ← 「Docker DNS 修復：用 host.docker.internal」
├── my-web-app/              ← 專案特定記憶（自動建立）
│   ├── architecture_decisions.md  ← 「Next.js 15 + Tailwind + Prisma」
│   └── known_issues.md      ← 「/dashboard 的 SSR hydration bug」
└── my-mobile-app/
    └── ...

因為是 Git：

git log 顯示何時做了什麼決策、為什麼
git diff 顯示兩次對話之間的知識變化
git branch 讓你實驗不同的架構方向
團隊成員可以透過 Pull Request 共享專案知識

Artifact-Gated DDD → BDD → TDD

遇到新功能或複雜邏輯時自動啟動（透過 ddd-bdd-tdd skill）：

1. DDD 階段 → AI 寫入 docs/ddd/<feature-name>.DDD.md
                定義 context、entity、event 與 INV/BR/OR rule ID
                你確認 ✓

2. BDD 階段 → AI 寫入 docs/bdd/<feature-name>.bdd.md
                設計 假如-當-那麼 場景，並標上 @rule:<RULE-ID>
                你確認 ✓

3. Feature Extraction → AI 執行專案既有抽取腳本
                       產生 test/features/<feature-name>.feature

4. TDD 階段 → AI 在 tests/unit/... 先寫 unit tests
                補 Cucumber step definitions，再實作

5. CI Verification → Unit tests、BDD scenarios、rule coverage 全過
                    交付程式碼 ✓

每個階段都需要你明確同意才會推進。簡單的 bug 修復和設定變更會自動跳過。

在撰寫測試前，AI 會在你的 codebase 中找 2 個以上類似實作，學習既有模式並重用既有工具。如果專案已經有 nyc cucumber-js，會用它做 BDD 反向覆蓋；否則跟隨專案既有測試指令，缺少抽取腳本或 BDD runner 時會明確回報，不會默默新增依賴。

驗證戳記

涉及程式碼的回應需有一個驗證階段戳記（透過 code-verification skill）：

戳記	含義
`📌 DDD Complete — Awaiting Confirmation`	領域模型待審查
`📌 BDD Complete — Awaiting Confirmation`	場景待審查
`✅ Tests: [X/X] \| Build: [Command]`	程式碼交付，測試通過
`✅ Build Verified: [Command]`	程式碼交付，建置確認
`⚠️ Verification Skipped: [Reason]`	純討論，無程式碼

若同一錯誤連續 3 次嘗試仍失敗，AI 會停下、記錄嘗試過的方法，並提出根本不同的方案（升級協議）。

自訂指南

本框架設計為 fork 後個人化使用。以下是你可以修改的項目與位置：

人格與語言

修改項目	檔案	預設值
AI 如何稱呼你	`system-prompt-v5.md` 或 `CLAUDE.md` → Core Identity 表格	`"dear" (親愛的)`
輸出語言	`system-prompt-v5.md` 或 `CLAUDE.md` → Core Identity 表格	`Traditional Chinese (繁體中文)`
性格語氣	`system-prompt-v5.md` 或 `CLAUDE.md` → Core Identity 表格	`Opinionated Neutrality`
溝通風格	`skills/warm-persona/SKILL.md`	溫暖、金字塔原則

預設技術棧

編輯 skills/tech-defaults/SKILL.md 修改預設技術選型（在沒有專案級定義時使用）。

提示： 這些只是預設值。每個專案的 architecture_decisions.md（在 AI-Brain 中）會覆蓋它們。

BDD 關鍵字

編輯 skills/ddd-bdd-tdd/SKILL.md 修改 Gherkin 關鍵字（預設：假如 / 當 / 那麼 / 而且）。

產品 UI 設計

編輯 skills/product-ui-designer/SKILL.md 與其 references/ 檔案，調整視覺設計規則、元件配方、頁面模式與 final polish 檢查。

Git 約定

編輯 skills/git-workflow/SKILL.md 修改提交訊息格式、分支命名和 PR 標準。

建立自訂 Skill

在 skills/ 下新增子目錄和 SKILL.md 即可建立你自己的 Skill：

skills/
└── my-custom-skill/
    └── SKILL.md

每個 SKILL.md 需要包含 YAML front matter（name 和 description，含觸發條件），接著是規則和流程。參考現有 Skills 了解格式。

相容性

本框架主要為 Claude Code 設計，提供完整 Skill 支援。其他工具亦可使用，功能程度有所不同：

工具	系統提示詞	Skills	AI-Brain	方法論
Claude Code	✅	✅ 原生	✅	✅ 完整
Gemini CLI	✅	⚠️ 打包/手動附加	✅	⚠️ 以提示詞驅動
OpenAI Codex	✅	✅ AGENTS.md + symlink Skills	✅	⚠️ 以提示詞驅動
其他 CLI 工具	✅	⚠️ 手動附加	✅	⚠️ 視工具而定

驗證戳記遵守率會隨模型與工具整合方式而不同。Claude Code 是主要目標環境；Gemini CLI、Codex 與其他工具更依賴提示詞遵循度與本地設定品質。如果某條規則沒有穩定生效，歡迎附上使用的工具、模型與設定方式開 issue。

貢獻

歡迎貢獻！你可以：

開 issue 回報 Bug、建議、或規則遵從問題
提交 PR 新增 Skill、改進、或翻譯
與社群分享你的自訂 Skill

授權

MIT

Name		Name	Last commit message	Last commit date
Latest commit History 24 Commits
_common		_common
_example		_example
claude		claude
gemini		gemini
scripts		scripts
skills		skills
.gitattributes		.gitattributes
.gitignore		.gitignore
AGENTS.md		AGENTS.md
CLAUDE.md		CLAUDE.md
LICENSE		LICENSE
README.md		README.md
setup.sh		setup.sh
system-prompt-v5.md		system-prompt-v5.md

Folders and files

Latest commit

History

Repository files navigation

AI Coding Flow

English

The Problem

The Solution

How It's Different

Architecture

Skills Reference

Project Structure

Quick Start

1. Clone the framework

2. Set up AI-Brain (your private memory)

3. Apply to your AI tool

How It Works

AI-Brain: Memory That Lives in Git

Artifact-Gated DDD → BDD → TDD

Verification Stamps

Customization Guide

Persona & Language

Tech Stack Defaults

BDD Keywords

Product UI Design

Git Conventions

Creating Custom Skills

Compatibility

Contributing

License

繁體中文

問題

解決方案

有何不同

架構

Skills 總覽

專案結構

快速開始

1. Clone 框架

2. 設定 AI-Brain（你的私有記憶）

3. 套用到你的 AI 工具

運作原理

AI-Brain：活在 Git 裡的記憶

Artifact-Gated DDD → BDD → TDD

驗證戳記

自訂指南

人格與語言

預設技術棧

BDD 關鍵字

產品 UI 設計

Git 約定

建立自訂 Skill

相容性

貢獻

授權

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages