File Structure

文件结构

ai-coding-ok 完整目录树，每个文件的功能说明。

---

仓库根目录

ai-coding-ok/
├── SKILL.md                          # Skill 定义入口（Mode A/B/C/D）
├── CLAUDE.md                         # Claude Code 自动加载 shim → @AGENTS.md
├── AGENTS.md                         # 架构速查（自用 dogfooding）
├── README.md                         # 英文 README（落地页）
├── README.zh.md                      # 中文 README
├── CHANGELOG.md                      # 版本历史
├── LICENSE                           # MIT
├── install.sh                        # Bash 安装脚本
├── install.py                        # Python 安装脚本（跨平台）
│
├── .claude-plugin/
│   └── plugin.json                   # 插件清单，用于 /plugin install
│
├── skills/
│   └── ai-coding-ok/
│       └── SKILL.md                  # 权威英文 Skill 定义
│
├── templates/                        # ← 产品源码——安装时不可修改
│   ├── en/                           # 英文模板（18 个文件）
│   └── zh/                           # 中文模板（相同结构）
│
├── scripts/
│   ├── verify.sh                     # 安装验证
│   ├── customize-prompt.md           # Copilot 手动定制提示
│   └── upgrade-prompt.md             # Copilot 手动升级提示
│
├── docs/
│   ├── claude-code-quickstart.md     # Claude Code 使用指南
│   ├── copilot-quickstart.md         # Copilot 使用指南
│   ├── superpowers-combo.md          # 与 superpowers 组合使用
│   ├── faq.md                        # 常见问题
│   └── hook-trigger-remediation-plan.md  # v4.1.0 防御系统设计文档
│
└── .github/                          # 自用 dogfooding（ai-coding-ok 自己的记忆）
    └── agent/
        ├── system-prompt.md
        ├── coding-standards.md
        ├── workflows.md
        ├── prompt-templates.md
        └── memory/
            ├── project-memory.md
            ├── decisions-log.md
            └── task-history.md

---

关键目录说明

templates/ — 产品

这是安装到用户项目中的所有文件的源。两种语言变体（en/ 和 zh/），结构相同。

规则： 安装或升级时绝不修改 templates/。只在开发 ai-coding-ok 本身时修改。

skills/ai-coding-ok/ — Skill 定义

Claude Code 加载插件时读取的权威 SKILL.md。这是 ai-coding-ok 的"大脑"。

根目录 SKILL.md 是旧版 git clone 用户的兼容副本。权威版本在 skills/ai-coding-ok/SKILL.md。

scripts/ — 自动化

脚本	用途	依赖
install.sh	安装 ai-coding-ok 到项目	仅 bash
install.py	同上，跨平台（Windows）	Python 3.8+ 标准库
verify.sh	检查安装完整性	仅 bash
customize-prompt.md	Copilot 填充占位符的提示	无（文本）
upgrade-prompt.md	Copilot 升级的提示	无（文本）

.github/ — 自用 dogfooding

ai-coding-ok 使用自己的记忆系统追踪自身开发。此 .github/ 目录是自用安装——与模板分离，不分发给用户。

---

安装到用户项目中的文件

<user-project>/
├── AGENTS.md                          # 架构速查（AI 最先读取）
├── CLAUDE.md                          # Claude Code 自动加载 → @AGENTS.md
├── .cursor/
│   └── rules/
│       └── ai-coding-ok.mdc           # Cursor：alwaysApply PDCA 规则
└── .github/
    ├── copilot-instructions.md        # Copilot：自动加载行为规则
    ├── project-metadata.yml           # 机器可读项目元信息
    ├── PULL_REQUEST_TEMPLATE.md       # PR 模板（含记忆更新检查）
    ├── ISSUE_TEMPLATE/                # Issue 模板
    ├── workflows/
    │   ├── ci.yml                     # CI 流水线模板
    │   └── memory-check.yml           # PR 记忆更新提醒
    └── agent/
        ├── system-prompt.md           # Agent 角色 + PDCA 工作流
        ├── coding-standards.md        # 编码规范
        ├── workflows.md               # 场景工作流
        ├── prompt-templates.md        # Prompt 模板库
        └── memory/
            ├── project-memory.md      # 🧠 长期：项目事实
            ├── decisions-log.md       # 📝 中期：ADR
            └── task-history.md        # 📜 短期：最近 30 条

---

数据流

graph LR
    subgraph "ai-coding-ok 仓库"
        TPL[templates/en/ + zh/]
        SKILL[skills/ai-coding-ok/SKILL.md]
    end
    subgraph "安装过程"
        COPY[复制文件]
        FILL[填充占位符]
        BOOT[初始化记忆]
    end
    subgraph "用户项目"
        AGENTS[AGENTS.md]
        MEMORY[.github/agent/memory/]
        HOOKS[.claude/settings.local.json]
    end
    subgraph "运行时"
        AI[AI 编码前读取记忆]
        ACT[AI 编码后写入记忆]
    end
    TPL --> COPY
    SKILL --> COPY
    COPY --> FILL --> BOOT
    BOOT --> AGENTS
    BOOT --> MEMORY
    BOOT --> HOOKS
    AGENTS --> AI
    MEMORY --> AI
    AI --> ACT
    ACT --> MEMORY

Loading

---

版本标记

每个已安装文件第一行有版本标记：

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

或

# ai-coding-ok: v4.1.0

升级系统使用这些标记检测已安装版本并确定要应用的变更。

---

下一步

• 模板系统 — 模板如何工作以及如何修改
• Hooks 系统 — Claude Code hooks 配置
• 版本管理 — 版本与升级机制