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 — 14 self-contained behavioral modules with embedded, mandatory-runtime, and conditional activation classes.
🏗️ 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, server, or API key. Python powers deterministic helpers; Node is used only by the executable Cucumber test runner.

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.1 uses a modular Skill architecture. Claude and Codex remain thin entrypoints, with the compact skill-feedback source as the only embedded Skill-body exception.

┌─────────────────────────────────────────────┐
│  System Prompt (system-prompt-v5.md)        │  ← Source orchestrator
│  Generated entrypoints                      │  ← CLAUDE.md / AGENTS.md / gemini/GEMINI.md
│  Core identity and Skill registry           │
├─────────────────────────────────────────────┤
│  Skills (skills/*/SKILL.md)                 │  ← Modular behavior
│  14 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
`skill-feedback`	Embedded Always Active	Detect feedback events and invoke the atomic production updater
`response-protocol`	Mandatory Runtime	Response order, action authority, progress and reporting rules
`ai-brain`	Mandatory Runtime	Tool-neutral AI-Brain context lifecycle and owned write-back
`role-adaptation`	Conditional	Architecture, research, domain, BDD, implementation, and review specialist focus
`ddd-bdd-tdd`	Conditional	Structured development: DDD artifacts → BDD specs → Cucumber features → TDD implementation
`implementation-principles`	Conditional	Project-first implementation through complete slices, cohesive boundaries, dependency reuse, and durable architecture
`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

skill-feedback is embedded once per conversation. Mandatory Runtime Skills load once from installed paths on the first turn. Conditional Skills activate only when their trigger descriptions match.

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                        ← Generated Claude Code entrypoint
├── AGENTS.md                        ← Generated Codex entrypoint
├── upgrade-plan.md                  ← Framework governance upgrade plan
├── claude/
│   ├── overlay.md                   ← Claude-specific prompt overlay
│   └── settings.json                ← Claude Code settings template (hooks + optional statusLine)
├── codex/
│   └── overlay.md                   ← Codex-specific prompt overlay
├── gemini/
│   ├── GEMINI.md                    ← Generated Gemini bundled prompt
│   ├── overlay.md                   ← Gemini-specific loading/fallback overlay
│   └── settings.json                ← Validated Gemini CLI hook settings (2 hooks)
├── scripts/
│   ├── generate-prompts.sh          ← Generates tool entrypoint prompts
│   ├── check-drift.sh               ← Checks generated prompts and repo metadata
│   ├── extract_features.py          ← Extracts authored BDD fences to generated Features
│   ├── check_rule_coverage.py       ← Validates rule tags, layers, and production subjects
│   ├── check_bdd_bindings.py        ← Validates semantic step bindings and Scenario oracles
│   ├── check_prompt_ownership.py    ← Validates prompt composition and ownership
│   ├── update_skill_experience.py   ← Atomic Skill Experience production updater
│   ├── run_bdd.py                   ← Strict Cucumber wrapper with manual exclusion count
│   ├── brain-loader.sh              ← SessionStart hook (AI-Brain Map injection)
│   ├── gemini-session-loader.sh     ← Gemini JSON context injection adapter
│   ├── 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)
│   ├── claude_stop_journal_gate.py  ← Claude Stop hook (blocks missing journal write-back)
│   └── 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.1)
    ├── skill-feedback/SKILL.md
    ├── role-adaptation/SKILL.md
    ├── response-protocol/SKILL.md
    ├── ai-brain/SKILL.md
    ├── ddd-bdd-tdd/SKILL.md
    ├── implementation-principles/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.

Setup prerequisite: Python 3.9+ is required. setup.sh does not require ripgrep or a package manager, and --dry-run performs the same generated-prompt validation without writing files. The executable BDD suite separately requires Node 22 || 24 || >=26; install its exact dependencies with npm ci. jq is optional for statusline.sh.

Verification commands:

Python/static bridge: scripts/check-drift.sh, python3 scripts/extract_features.py --check, and python3 scripts/check_rule_coverage.py
Node Cucumber runner: npm ci, then npm run test:bdd
Complete automated suite: npm test

check-drift.sh intentionally does not run Cucumber or claim model-behavior success. Manual @layer:model @manual cases remain separate.

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):

Links all non-embedded Skills to ~/.claude/skills/; skill-feedback stays embedded only
Symlinks CLAUDE.md to ~/.claude/CLAUDE.md
Symlinks Claude hook scripts and the Skill Experience updater 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.
claude_stop_journal_gate.py (Stop) — Reads current-turn transcript tool calls and blocks completion when project code/config—including active prompt Markdown—has no later sibling AI-Brain journal.md update. README and DDD/BDD documentation edits are excluded.

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):

Checks generated prompts for drift, then copies gemini/GEMINI.md to ~/.gemini/GEMINI.md
Links all non-embedded Skills for Mandatory fallback and Conditional use
Symlinks gemini-session-loader.sh, AI-Brain helpers, and the Skill Experience updater
Merges hooks into ~/.gemini/settings.json and migrates matching managed legacy direct-command entries—including the former SessionStart brain-loader.sh alias—to native nested handlers

The generated prompt embeds only skill-feedback as always active and bundles role-adaptation for conditional availability. Mandatory Skills come from the SessionStart marker or installed-path fallback.

Hook contract: SessionStart and BeforeTool use Gemini's native nested hooks[] command-handler schema. The SessionStart command returns exactly one JSON object and injects context through hookSpecificOutput.additionalContext. Static checks validate the schema; integration tests also verify real registry acceptance when Gemini CLI is installed. Installed-path fallback remains available when hooks are disabled or unavailable.

Manual alternative (per-project):

mkdir -p .gemini
cp ~/Documents/GitHub/ai-coding-flow/gemini/GEMINI.md .gemini/GEMINI.md

Generated prompts should not be edited by hand. Edit sources or overlays, run scripts/generate-prompts.sh, then verify with scripts/check-drift.sh.

OpenAI Codex

What setup.sh does (option 3):

Checks generated prompts for drift, then copies AGENTS.md to ~/.codex/AGENTS.md
Symlinks the Skill Experience updater to ~/.codex/scripts/
Symlinks each complete non-embedded Skill directory to ~/.codex/skills/<skill-name>
When the stable hooks feature is enabled, installs content-addressed lifecycle commands in ~/.codex/hooks.json without granting trust

Codex natively discovers linked Skills and can run this repo's capability-scoped Cooperative Guardrails through SessionStart, UserPromptSubmit, PreToolUse, and Stop. Runtime executable attestation protects the content-addressed dispatcher; a reusable Epoch Registration and turn-scoped replay protection bind model-visible evidence to the current context. Review exact definitions in Codex before trusting them.

Use Manual Hook Fallback when hooks are unsupported, disabled, untrusted, unobserved, failed, or missing current-transition evidence. User-level hooks are cooperative rather than complete enforcement because project, plugin, managed, or other user hooks may also run. SessionEnd is documented but intentionally deferred; the private lifecycle state already has a 24-hour TTL.

Manual alternative (per-project):

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

For reusable Skill support, copy or symlink each complete skills/<skill-name>/ directory into ~/.codex/skills/. Do not create a real Skill directory containing only a symlinked SKILL.md; Codex does not discover that layout.

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 Incomplete: [Reason]`	Required verification remains incomplete; no success claim
`⚠️ 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).

Runnable Application Startup Verification

Startup verification is risk-based: it is required when an implementation task affects a runnable application path or claims the application complete. The AI reconciles project documentation with executable manifests, scripts, and runtime configuration; exercises each required entrypoint in a safe local or explicitly designated test environment through a representative workflow and lazy initialization; and verifies clean shutdown. A ready signal or process-manager status alone is not sufficient runtime evidence. Real-production, destructive, or out-of-scope operations still require separate explicit authorization, and no tool hook is claimed to observe application startup. Missing required evidence uses the incomplete stamp above and cannot produce a green success stamp.

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` → Core Identity	`親愛的`
Output language	`system-prompt-v5.md` → Core Identity	Traditional Chinese
Personality tone	`system-prompt-v5.md` → Core Identity	Opinionated neutrality
Response structure	`skills/response-protocol/SKILL.md`	Conclusion → reasoning → details

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	✅	⚠️ Cooperative hooks + fallback
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.

Enforcement Levels

Rule	Claude Code	Gemini CLI	OpenAI Codex
AI-Brain first-message loading	hook-enforced	hook-enforced with manual fallback	cooperative hook + manual fallback
Journal write-back after code/config edits	hook-enforced	prompt-enforced	cooperative hook
No `Co-Authored-By` trailers	hook-enforced	prompt-enforced	cooperative hook
Code on Demand / review-only authorization	prompt-enforced	prompt-enforced	prompt-enforced
DDD / BDD phase gates	manual-confirmed	manual-confirmed	manual-confirmed
Progress Continuity	prompt-enforced	prompt-enforced	prompt-enforced
Checkpoint Verification	prompt-enforced	prompt-enforced	prompt-enforced
Runnable Application Startup Verification	prompt-enforced	prompt-enforced	prompt-enforced

hook-enforced means an external mechanism can block or remind. prompt-enforced means the model is instructed but not externally blocked. manual-confirmed means the user must confirm before the next phase proceeds.

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 — 14 個獨立行為模組，分成嵌入常駐、Mandatory Runtime 與條件觸發三類。
🏗️ 結構化方法論 — 強制執行 artifact-gated DDD → BDD → TDD，包含 Cucumber feature 抽取與規則追溯。
✅ 可驗證的輸出 — 涉及程式碼或設定變更時，回應結尾會附上驗證戳記，說明驗證了什麼、跳過了什麼。
📚 跨專案學習 — Common AI-Brain 在所有專案間積累智慧。修過一次 Docker DNS 問題，所有專案都知道解法。
📦 無執行期服務依賴 — 不需要資料庫、伺服器或 API key。Python 負責可判定 helper；Node 只用於可執行 Cucumber runner。

有何不同

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

架構

v5.1 採用模組化 Skill 架構。Claude 與 Codex 維持精簡入口，只有小型 skill-feedback 是唯一完整嵌入的 Skill 正文例外。

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

Skills 總覽

Skill	類型	用途
`skill-feedback`	嵌入常駐	偵測 feedback event 並呼叫原子化 production updater
`response-protocol`	Mandatory Runtime	回應順序、行動授權、進度與報告規則
`ai-brain`	Mandatory Runtime	工具中立的 AI-Brain context lifecycle 與 owned write-back
`role-adaptation`	條件觸發	架構、研究、領域、BDD、實作與 review 專家焦點
`ddd-bdd-tdd`	條件觸發	結構化開發：DDD artifact → BDD 規格 → Cucumber feature → TDD 實作
`implementation-principles`	條件觸發	以專案證據、完整切片、內聚邊界、依賴重用與可持續架構引導實作
`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-feedback 每次對話完整嵌入一次；Mandatory Runtime Skills 在 first turn 從安裝路徑載入一次；條件 Skill 只在 description 命中時啟動。

專案結構

ai-coding-flow/
├── README.md
├── LICENSE
├── .gitignore
├── setup.sh                        ← 多工具安裝腳本（Claude / Gemini / Codex）
├── system-prompt-v5.md              ← 核心系統提示詞原始檔（協調者）
├── CLAUDE.md                        ← 生成的 Claude Code 入口
├── AGENTS.md                        ← 生成的 Codex 入口
├── upgrade-plan.md                  ← 框架治理升級計畫
├── claude/
│   ├── overlay.md                   ← Claude 專用提示詞覆蓋層
│   └── settings.json                ← Claude Code 設定模板（hooks + 可選 statusLine）
├── codex/
│   └── overlay.md                   ← Codex 專用提示詞覆蓋層
├── gemini/
│   ├── GEMINI.md                    ← 生成的 Gemini 打包提示詞
│   ├── overlay.md                   ← Gemini 專用載入與 fallback overlay
│   └── settings.json                ← 已驗證的 Gemini CLI hook 設定（2 個 hook）
├── scripts/
│   ├── generate-prompts.sh          ← 生成工具入口提示詞
│   ├── check-drift.sh               ← 檢查生成提示詞與 repo metadata
│   ├── extract_features.py          ← 從 BDD fence 產生 Feature
│   ├── check_rule_coverage.py       ← 驗證 rule tag、layer 與 production subject
│   ├── check_bdd_bindings.py        ← 驗證語意 step 綁定與 Scenario oracle
│   ├── check_prompt_ownership.py    ← 驗證 prompt 組合與所有權
│   ├── update_skill_experience.py   ← 原子化 Skill Experience updater
│   ├── run_bdd.py                   ← 嚴格 Cucumber wrapper 與 manual 排除計數
│   ├── brain-loader.sh              ← SessionStart hook（AI-Brain Map 注入到 context）
│   ├── gemini-session-loader.sh     ← Gemini JSON context 注入 adapter
│   ├── brain-gate.sh                ← PreToolUse hook（強制先回應再用工具）
│   ├── no-coauthor-guard.sh         ← PreToolUse hook（攔截 Co-Authored-By 提交）
│   ├── journal-reminder.sh          ← PreToolUse hook（提醒更新 journal.md）
│   ├── claude_stop_journal_gate.py  ← Claude Stop hook（攔截缺少 journal write-back）
│   └── 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.1)
    ├── skill-feedback/SKILL.md
    ├── role-adaptation/SKILL.md
    ├── response-protocol/SKILL.md
    ├── ai-brain/SKILL.md
    ├── ddd-bdd-tdd/SKILL.md
    ├── implementation-principles/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/ 下的檔案。腳本現在會在實際寫入前先顯示確認提示。若你已經有自訂的全域設定，請先檢查或備份。

安裝前置條件： 只需要 Python 3.9+。setup.sh 不依賴 ripgrep 或任何套件管理器，--dry-run 也會執行相同的生成提示詞驗證但不寫入檔案。可執行 BDD 測試另需 Node 22 || 24 || >=26，並用 npm ci 安裝 exact dependencies。jq 只在 statusline.sh 使用。

驗證指令：

Python／static bridge：scripts/check-drift.sh、python3 scripts/extract_features.py --check、python3 scripts/check_rule_coverage.py
Node Cucumber runner：先執行 npm ci，再執行 npm run test:bdd
完整自動化套件：npm test

check-drift.sh 刻意不執行 Cucumber，也不宣稱 model behavior 已通過。@layer:model @manual cases 維持獨立人工驗證。

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

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

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

將非嵌入 Skills 連結到 ~/.claude/skills/；skill-feedback 只保留嵌入版本
將 CLAUDE.md symlink 到 ~/.claude/CLAUDE.md
將 Claude hook scripts 與 Skill Experience updater 連結到 ~/.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（硬攔截）形成雙層防線。
claude_stop_journal_gate.py（Stop） — 讀取本輪 transcript 的 tool calls；若專案程式／設定（包含 active prompt Markdown）修改後沒有較晚的 sibling AI-Brain journal.md 更新，就阻擋結束。README 與 DDD/BDD 文件修改不觸發。

狀態列：

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）：

檢查 generated prompts 是否漂移，然後複製 gemini/GEMINI.md 到 ~/.gemini/GEMINI.md
安裝非嵌入 Skills，供 Mandatory fallback 與 Conditional 使用
安裝 gemini-session-loader.sh、AI-Brain helpers 與 Skill Experience updater
將 hooks 合併到 ~/.gemini/settings.json，並把匹配的 managed 舊版 direct-command entries（包含先前 SessionStart 的 brain-loader.sh alias）遷移為原生巢狀 handlers

生成提示詞只將 skill-feedback 完整常駐嵌入，並為條件可用性打包 role-adaptation。Mandatory Skills 由 SessionStart marker 或安裝路徑 fallback 載入。

Hook 合約： SessionStart 與 BeforeTool 使用 Gemini 原生的巢狀 hooks[] command-handler schema。SessionStart command 只回傳一個 JSON object，並透過 hookSpecificOutput.additionalContext 注入 context。靜態檢查驗證 schema；安裝 Gemini CLI 時，整合測試也會驗證真實 registry 接受度。hooks 停用或不可用時仍保留安裝路徑 fallback。

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

mkdir -p .gemini
cp ~/Documents/GitHub/ai-coding-flow/gemini/GEMINI.md .gemini/GEMINI.md

生成提示詞不應手改。請修改來源或 overlay，執行 scripts/generate-prompts.sh，再用 scripts/check-drift.sh 驗證。

OpenAI Codex

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

檢查 generated prompts 是否漂移，然後複製 AGENTS.md 到 ~/.codex/AGENTS.md
將 Skill Experience updater symlink 到 ~/.codex/scripts/
將每個完整的非嵌入 Skill 目錄 symlink 到 ~/.codex/skills/<skill-name>
stable hooks feature 已啟用時，在 ~/.codex/hooks.json 安裝內容定址的 lifecycle commands，但不代替使用者授予 trust

Codex 能原生探索連結的 Skills，並透過 SessionStart、UserPromptSubmit、PreToolUse 與 Stop 執行能力分層的 Cooperative Guardrails。runtime executable attestation 保護內容定址 dispatcher；可重用的 Epoch Registration 與 turn-scoped replay protection 將模型可見證據綁定到目前 context。請先在 Codex 審查 exact definitions，再自行授予 trust。

當 hooks 不支援、停用、未信任、未觀察、失敗，或缺少目前 transition evidence 時，使用 Manual Hook Fallback。user-level hooks 屬於 cooperative guardrails，而非完整 enforcement，因為 project、plugin、managed 或其他 user hooks 也可能執行。SessionEnd 已有文件但 intentionally deferred；private lifecycle state 已有 24 小時 TTL。

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

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

如需可重用的 Skill 支援，請將每個完整的 skills/<skill-name>/ 目錄複製或 symlink 到 ~/.codex/skills/。不要建立真實 Skill 目錄後只 symlink 其中的 SKILL.md；Codex 不會探索這種布局。

其他 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 Incomplete: [Reason]`	必要驗證仍未完成；不得宣稱成功
`⚠️ Verification Skipped: [Reason]`	純討論，無程式碼

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

可執行應用程式啟動驗證

啟動驗證採風險判定：當實作工作影響可執行應用程式路徑，或宣稱應用程式已完成時，才屬必要項目。AI 會核對專案文件與可執行 manifest、script 及 runtime 設定；在安全的本機或明確指定的測試環境中逐一啟動必要入口，執行代表性 workflow、跨過 lazy initialization，並驗證乾淨關閉。只有 ready signal 或 process-manager 狀態不足以作為完整 runtime evidence。真實 production、破壞性或超出範圍的操作仍需另外明確授權，且不宣稱任何 tool hook 能觀察 application startup。必要證據缺失時必須使用上述 incomplete stamp，不得輸出綠色成功戳記。

自訂指南

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

人格與語言

修改項目	檔案	預設值
AI 如何稱呼你	`system-prompt-v5.md` → Core Identity	`親愛的`
輸出語言	`system-prompt-v5.md` → Core Identity	繁體中文
性格語氣	`system-prompt-v5.md` → Core Identity	Opinionated neutrality
回應結構	`skills/response-protocol/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	✅	⚠️ Cooperative hooks + fallback
其他 CLI 工具	✅	⚠️ 手動附加	✅	⚠️ 視工具而定

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

強制力等級

規則	Claude Code	Gemini CLI	OpenAI Codex
AI-Brain 首訊息載入	hook-enforced	hook-enforced（含手動 fallback）	cooperative hook + manual fallback
程式/設定改動後 journal write-back	hook-enforced	prompt-enforced	cooperative hook
禁止 `Co-Authored-By` trailers	hook-enforced	prompt-enforced	cooperative hook
Code on Demand / review-only 授權	prompt-enforced	prompt-enforced	prompt-enforced
DDD / BDD 階段 gate	manual-confirmed	manual-confirmed	manual-confirmed
Progress Continuity	prompt-enforced	prompt-enforced	prompt-enforced
Checkpoint Verification	prompt-enforced	prompt-enforced	prompt-enforced
可執行應用程式啟動驗證	prompt-enforced	prompt-enforced	prompt-enforced

hook-enforced 表示有外部機制可攔截或提醒。prompt-enforced 表示模型收到規則，但沒有外部攔截。manual-confirmed 表示進入下一階段前需要使用者確認。

貢獻

歡迎貢獻！你可以：

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

授權

MIT

Name		Name	Last commit message	Last commit date
.github/workflows		.github/workflows
_common		_common
_example		_example
claude		claude
codex		codex
docs		docs
gemini		gemini
scripts		scripts
skills		skills
test/features/prompt-ownership-refactor		test/features/prompt-ownership-refactor
tests		tests
.gitattributes		.gitattributes
.gitignore		.gitignore
AGENTS.md		AGENTS.md
CHANGELOG.md		CHANGELOG.md
CLAUDE.md		CLAUDE.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
README.md		README.md
cucumber.cjs		cucumber.cjs
ddd-to-bdd.md		ddd-to-bdd.md
package-lock.json		package-lock.json
package.json		package.json
setup.sh		setup.sh
system-prompt-v5.md		system-prompt-v5.md
upgrade-plan.md		upgrade-plan.md

Latest commit

History

Folders and files

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

Runnable Application Startup Verification

Customization Guide

Persona & Language

Tech Stack Defaults

BDD Keywords

Product UI Design

Git Conventions

Creating Custom Skills

Compatibility

Enforcement Levels

Contributing

License

繁體中文

問題

解決方案

有何不同

架構

Skills 總覽

專案結構

快速開始

1. Clone 框架

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

3. 套用到你的 AI 工具

運作原理

AI-Brain：活在 Git 裡的記憶

Artifact-Gated DDD → BDD → TDD

驗證戳記

可執行應用程式啟動驗證

自訂指南

人格與語言

預設技術棧

BDD 關鍵字

產品 UI 設計

Git 約定

建立自訂 Skill

相容性

強制力等級

貢獻

授權

About

Resources

Contributing

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages