From 04460ad07e025a1c8a171588b0790cabdb15a68e Mon Sep 17 00:00:00 2001 From: li Date: Wed, 11 Mar 2026 23:37:37 +0800 Subject: [PATCH] feat: /ccg:context command + quality gate rules v1.7.80 MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - /ccg:context: 27th slash command — .context/ init, decision log, compress, history for LLM context engineering - /ccg:commit Context Compress Phase: auto-compress session.log → history/commits.jsonl on commit, add Context-Id trailer - 13 role prompts .context Awareness: Codex 6 + Gemini 7 prompts inject .context/prefs/ reading instructions - Quality Gate Rules: ~/.claude/rules/ccg-skills.md auto-trigger rules for verify-security/quality/change/module + gen-docs - E2E test timeout 5s → 15s for growing command count --- CHANGELOG.md | 17 + CLAUDE.md | 18 +- README.md | 3 +- README.zh-CN.md | 5 +- package.json | 6 +- src/commands/init.ts | 8 + src/types/index.ts | 1 + src/utils/__tests__/installWorkflows.test.ts | 2 +- src/utils/installer.ts | 57 ++++ templates/commands/commit.md | 24 +- templates/commands/context.md | 330 +++++++++++++++++++ templates/prompts/codex/analyzer.md | 8 + templates/prompts/codex/architect.md | 8 + templates/prompts/codex/debugger.md | 8 + templates/prompts/codex/optimizer.md | 7 + templates/prompts/codex/reviewer.md | 7 + templates/prompts/codex/tester.md | 7 + templates/prompts/gemini/analyzer.md | 8 + templates/prompts/gemini/architect.md | 8 + templates/prompts/gemini/debugger.md | 8 + templates/prompts/gemini/frontend.md | 8 + templates/prompts/gemini/optimizer.md | 7 + templates/prompts/gemini/reviewer.md | 7 + templates/prompts/gemini/tester.md | 7 + templates/rules/ccg-skills.md | 63 ++++ 25 files changed, 621 insertions(+), 11 deletions(-) create mode 100644 templates/commands/context.md create mode 100644 templates/rules/ccg-skills.md diff --git a/CHANGELOG.md b/CHANGELOG.md index d810d51..131a939 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -7,6 +7,23 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 --- +## [1.7.80] - 2026-03-11 + +### ✨ 新功能 + +- **`/ccg:context` 命令**：第 27 个斜杠命令，项目上下文管理（`.context/` 目录初始化、决策日志记录、压缩归档、历史查看） +- **`.context` 上下文工程体系**：为 LLM 全面自动化提供决策审计链 — 记录 WHY（为什么改）、WHAT（考虑了什么替代方案）、BUG（遇到了什么坑） +- **ContextEntry Schema v1.0.0**：JSONL canonical store + Markdown 人类视图，UUIDv7 主键（rebase-safe），`.gitattributes merge=union` 减少冲突 +- **`/ccg:commit` Context Compress Phase**：提交时自动压缩 session.log → 脱敏 → 追加 history/commits.jsonl → 添加 `Context-Id` commit trailer +- **13 个角色提示词 `.context Awareness` 注入**：Codex 6 个 + Gemini 7 个角色提示词增加 `.context/prefs/` 读取指令，外部模型自动遵守项目规范 +- **Quality Gate Rules 全局规则**：安装时自动写入 `~/.claude/rules/ccg-skills.md`，定义 5 个质量关卡的自动触发条件（新建模块/代码变更>30行/安全变更/重构） + +### 🔧 修复 + +- **E2E 测试超时**：`installWorkflows` 测试从 5s 提升到 15s，适应命令数量增长 + +--- + ## [1.7.79] - 2026-03-11 ### 🐛 修复 diff --git a/CLAUDE.md b/CLAUDE.md index 989af70..4768bb6 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -2,7 +2,7 @@ > [根目录](../CLAUDE.md) > **skills-v2** -**Last Updated**: 2026-03-11 (v1.7.79) +**Last Updated**: 2026-03-11 (v1.7.80) --- @@ -10,6 +10,12 @@ > 完整变更历史请查看 [CHANGELOG.md](./CHANGELOG.md) +### 2026-03-11 (v1.7.80) +- ✨ **`/ccg:context` 命令**：第 27 个斜杠命令，`.context/` 目录初始化 + 决策日志 + 压缩归档 + 历史查看 +- ✨ **Context Compress Phase**：`/ccg:commit` 提交时自动压缩 session.log → history/commits.jsonl +- ✨ **13 个角色提示词 `.context Awareness`**：Codex/Gemini 提示词注入 `.context/prefs/` 读取指令 +- ✨ **Quality Gate Rules**：`~/.claude/rules/ccg-skills.md` 定义质量关卡自动触发规则，安装时自动写入 + ### 2026-03-11 (v1.7.79) - 🐛 **Binary 下载容错**：3 次重试 + 60s 超时 + 失败醒目告警（红框 + 手动修复指引）+ 不阻塞安装 - 🐛 **Update 流程加固**：binary 备份/恢复 + subprocess 超时 120s→300s @@ -96,7 +102,7 @@ **CCG (Claude + Codex + Gemini)** - 多模型协作系统的核心实现，提供： 1. **多模型协作编排**：固定路由 Gemini（前端）+ Codex（后端）+ Claude（编排） -2. **26 个斜杠命令**：开发工作流 + Git 工具 + 项目管理 + OPSX + Agent Teams + Codex 执行 +2. **27 个斜杠命令**：开发工作流 + Git 工具 + 项目管理 + OPSX + Agent Teams + Codex 执行 3. **13 个专家提示词**：Codex 6 个 + Gemini 7 个 4. **6 个原生 Skills**：质量关卡（verify-security/quality/change/module + gen-docs）+ 多 Agent 协同 5. **跨平台 CLI 工具**：一键安装（支持 macOS、Linux、Windows） @@ -159,6 +165,7 @@ npx ccg-workflow menu | `/ccg:plan` | 多模型协作规划（Phase 1-2） | Codex ∥ Gemini | | `/ccg:execute` | 多模型协作执行（Phase 3-5） | Codex ∥ Gemini + Claude | | `/ccg:codex-exec` | Codex 全权执行计划（MCP + 代码 + 测试） | Codex + 多模型审核 | +| `/ccg:context` | 项目上下文管理（.context 初始化/日志/压缩/历史） | Claude | | `/ccg:frontend` | 前端专项（快速模式） | Gemini | | `/ccg:backend` | 后端专项（快速模式） | Codex | | `/ccg:feat` | 智能功能开发 | 规划 → 实施 | @@ -201,7 +208,7 @@ v1.7.0 起，以下配置不再支持自定义： | 前端模型 | Gemini | 擅长 UI/CSS/组件 | | 后端模型 | Codex | 擅长逻辑/算法/调试 | | 协作模式 | smart | 最佳实践 | -| 命令数量 | 26 个 | 全部安装 | +| 命令数量 | 27 个 | 全部安装 | --- @@ -260,11 +267,12 @@ src/ ``` templates/ -├── commands/ # 26 个斜杠命令 +├── commands/ # 27 个斜杠命令 │ ├── workflow.md │ ├── plan.md # 多模型协作规划 │ ├── execute.md # 多模型协作执行 │ ├── codex-exec.md # Codex 全权执行计划 +│ ├── context.md # 项目上下文管理（.context） │ ├── frontend.md │ ├── backend.md │ ├── feat.md @@ -300,6 +308,8 @@ templates/ │ └── lib/ └── orchestration/ └── multi-agent/ +├── rules/ # 全局规则（→ ~/.claude/rules/） +│ └── ccg-skills.md # 质量关卡自动触发规则 ``` ### 预编译产物 diff --git a/README.md b/README.md index 2ca884d..b9c0a72 100644 --- a/README.md +++ b/README.md @@ -17,7 +17,7 @@ A multi-model collaboration development system where Claude Code orchestrates Co - **Zero-config model routing** — Frontend tasks automatically go to Gemini, backend tasks to Codex. No manual switching. - **Security by design** — External models have no write access. They return patches; Claude reviews before applying. -- **26 slash commands** — From planning to execution, git workflow to code review, all accessible via `/ccg:*`. +- **27 slash commands** — From planning to execution, git workflow to code review, all accessible via `/ccg:*`. - **Spec-driven development** — Integrates [OPSX](https://github.com/fission-ai/opsx) to turn vague requirements into verifiable constraints, eliminating AI improvisation. ## Architecture @@ -141,6 +141,7 @@ Supports: npm, homebrew, curl, powershell, cmd. | Command | Description | |---------|-------------| | `/ccg:init` | Initialize project CLAUDE.md | +| `/ccg:context` | Project context management (.context/ init, log, compress, history) | ## Workflow Guides diff --git a/README.zh-CN.md b/README.zh-CN.md index 7ae8b95..29dc51f 100644 --- a/README.zh-CN.md +++ b/README.zh-CN.md @@ -17,7 +17,7 @@ Claude Code 编排 Codex + Gemini 的多模型协作开发系统。前端任务 - **零配置模型路由** — 前端任务自动走 Gemini，后端任务自动走 Codex，无需手动切换。 - **安全设计** — 外部模型无写入权限，仅返回 Patch，由 Claude 审核后应用。 -- **26 个斜杠命令** — 从规划到执行、Git 工作流到代码审查，通过 `/ccg:*` 一站式访问。 +- **27 个斜杠命令** — 从规划到执行、Git 工作流到代码审查，通过 `/ccg:*` 一站式访问。 - **规范驱动开发** — 集成 [OPSX](https://github.com/fission-ai/opsx)，将模糊需求变成可验证约束，让 AI 没法自由发挥。 ## 架构 @@ -141,6 +141,7 @@ npx ccg-workflow menu # 选择「安装 Claude Code」 | 命令 | 说明 | |------|------| | `/ccg:init` | 初始化项目 CLAUDE.md | +| `/ccg:context` | 项目上下文管理（.context 初始化/日志/压缩/历史） | ## 工作流指南 @@ -196,7 +197,7 @@ npx ccg-workflow menu # 选择「安装 Claude Code」 ``` ~/.claude/ -├── commands/ccg/ # 26 个斜杠命令 +├── commands/ccg/ # 27 个斜杠命令 ├── agents/ccg/ # 子智能体 ├── skills/ccg/ # 质量关卡 + 多 Agent 协同 ├── bin/codeagent-wrapper diff --git a/package.json b/package.json index d60a825..19cc3ac 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "ccg-workflow", - "version": "1.7.79", + "version": "1.7.80", "description": "Claude + Codex + Gemini multi-model collaboration system - smart routing development workflow", "type": "module", "packageManager": "pnpm@10.17.1", @@ -54,6 +54,7 @@ "templates/commands/team-exec.md", "templates/commands/team-review.md", "templates/commands/codex-exec.md", + "templates/commands/context.md", "templates/commands/agents/", "templates/prompts/codex/", "templates/prompts/gemini/analyzer.md", @@ -65,7 +66,8 @@ "templates/prompts/gemini/tester.md", "templates/prompts/claude/", "templates/output-styles/", - "templates/skills/" + "templates/skills/", + "templates/rules/" ], "scripts": { "dev": "tsx src/cli.ts", diff --git a/src/commands/init.ts b/src/commands/init.ts index f46a438..eddad60 100644 --- a/src/commands/init.ts +++ b/src/commands/init.ts @@ -810,6 +810,14 @@ export async function init(options: InitOptions = {}): Promise { console.log(ansis.gray(' → ~/.claude/skills/')) } + // Show installed rules + if (result.installedRules) { + console.log() + console.log(ansis.cyan(' Rules:')) + console.log(` ${ansis.green('✓')} quality gate auto-trigger rules`) + console.log(ansis.gray(' → ~/.claude/rules/ccg-skills.md')) + } + // Show errors if any if (result.errors.length > 0) { console.log() diff --git a/src/types/index.ts b/src/types/index.ts index 33826ed..7024219 100644 --- a/src/types/index.ts +++ b/src/types/index.ts @@ -87,6 +87,7 @@ export interface InstallResult { installedCommands: string[] installedPrompts: string[] installedSkills?: number + installedRules?: boolean errors: string[] configPath: string binPath?: string diff --git a/src/utils/__tests__/installWorkflows.test.ts b/src/utils/__tests__/installWorkflows.test.ts index 53df528..49cb986 100644 --- a/src/utils/__tests__/installWorkflows.test.ts +++ b/src/utils/__tests__/installWorkflows.test.ts @@ -39,7 +39,7 @@ describe('installWorkflows E2E — mcpProvider="skip"', () => { expect(result.success).toBe(true) expect(result.errors).toEqual([]) expect(result.installedCommands.length).toBeGreaterThan(0) - }) + }, 15000) it('generated command files contain no mcp__ace-tool references', async () => { const cmdDir = join(tmpDir, 'commands', 'ccg') diff --git a/src/utils/installer.ts b/src/utils/installer.ts index ee8c032..693ff6f 100644 --- a/src/utils/installer.ts +++ b/src/utils/installer.ts @@ -110,6 +110,7 @@ const ALL_COMMANDS = [ 'team-exec', // Agent Teams 并行实施（spawn Builders 并行写代码） 'team-review', // Agent Teams 审查（双模型交叉审查并行产出） 'codex-exec', // 读取计划文件，Codex 全权执行 + 多模型审核 + 'context', // 项目上下文管理（.context 目录初始化/日志/压缩/历史） ] as const // Workflow configurations (for compatibility with existing code) @@ -411,6 +412,17 @@ const WORKFLOW_CONFIGS: WorkflowConfig[] = [ description: '读取 /ccg:plan 计划文件，Codex 全权执行 + 多模型审核', descriptionEn: 'Read plan file from /ccg:plan, Codex executes + multi-model review', }, + { + id: 'context', + name: '项目上下文管理', + nameEn: 'Project Context Manager', + category: 'development', + commands: ['context'], + defaultSelected: true, + order: 4, + description: '初始化 .context 目录、记录决策日志、压缩归档、查看历史', + descriptionEn: 'Init .context dir, log decisions, compress, view history', + }, ] export function getWorkflowConfigs(): WorkflowConfig[] { @@ -845,6 +857,31 @@ ${workflow.description} } } + // Install rules (quality gate auto-trigger → ~/.claude/rules/ccg-skills.md) + const rulesTemplateDir = join(templateDir, 'rules') + const rulesDestDir = join(installDir, 'rules') + if (await fs.pathExists(rulesTemplateDir)) { + try { + await fs.ensureDir(rulesDestDir) + const rulesFiles = await fs.readdir(rulesTemplateDir) + for (const file of rulesFiles) { + if (file.endsWith('.md')) { + const srcFile = join(rulesTemplateDir, file) + const destFile = join(rulesDestDir, file) + if (force || !(await fs.pathExists(destFile))) { + const templateContent = await fs.readFile(srcFile, 'utf-8') + const processedContent = replaceHomePathsInTemplate(templateContent, installDir) + await fs.writeFile(destFile, processedContent, 'utf-8') + } + } + } + result.installedRules = true + } + catch (error) { + result.errors.push(`Failed to install rules: ${error}`) + } + } + // Install codeagent-wrapper binary try { const binDir = join(installDir, 'bin') @@ -915,6 +952,7 @@ export interface UninstallResult { removedPrompts: string[] removedAgents: string[] removedSkills: string[] + removedRules: boolean removedBin: boolean errors: string[] } @@ -929,6 +967,7 @@ export async function uninstallWorkflows(installDir: string): Promise/session.log` 是否存在且非空 +3. 若有内容： + - **脱敏**：扫描 token/key/password/secret 模式 → 替换为 `[REDACTED]` + - **压缩**：从 session.log 提取 decisions / bugs / alternatives，生成 ContextEntry JSON + - **追加**：将 ContextEntry 作为一行追加到 `.context/history/commits.jsonl` + - **重生成**：更新 `.context/history/commits.md` 人类视图 + - **暂存**：`git add .context/history/` + - **清空**：清空 session.log（不删除文件） + - **Trailer**：在 commit message 中添加 `Context-Id: ` trailer +4. 若 session.log 为空或不存在，跳过此阶段 + +**ContextEntry 格式**参见 `/ccg:context` 命令中的 Schema 定义。 + +**失败降级**：若压缩过程出错，不阻断提交。写入 minimal ContextEntry（仅 summary + error），继续正常提交。 + +### ✅ 阶段 6：执行提交 `[模式：执行]` diff --git a/templates/commands/context.md b/templates/commands/context.md new file mode 100644 index 0000000..389152c --- /dev/null +++ b/templates/commands/context.md @@ -0,0 +1,330 @@ +--- +description: '项目上下文管理：初始化 .context 目录、记录决策日志、压缩归档、查看历史' +--- + +# Context - 项目上下文管理 + +管理 `.context/` 目录结构，为 LLM 工具提供决策审计链。 + +## 使用方法 + +```bash +/context [options] +``` + +## 子命令 + +| 子命令 | 说明 | +|--------|------| +| `init` | 初始化 `.context/` 目录结构 | +| `log ` | 手动追加决策日志到 session.log | +| `show` | 查看当前分支的 session.log | +| `compress` | 压缩 session.log → uncommit.md | +| `history` | 查看 history/commits.md | +| `squash ` | 合并多条 history 记录（配合 git squash） | + +--- + +## 执行工作流 + +### 子命令：init + +`[模式：初始化]` + +在当前项目根目录创建 `.context/` 结构： + +1. 检测项目根目录（查找 `.git/`） +2. 若 `.context/` 已存在，跳过已有文件，仅补全缺失 +3. 创建以下结构： + +``` +.context/ +├── .gitignore +├── .gitattributes +├── prefs/ +│ ├── coding-style.md +│ └── workflow.md +├── current/ +│ └── branches/ +│ └── .gitkeep +└── history/ + ├── commits.jsonl + ├── commits.md + └── archives/ + └── .gitkeep +``` + +4. **创建 `.context/.gitignore`**： + +```gitignore +# Ephemeral workspace — never commit +current/ + +# Raw interaction logs — always local only +**/session.log +**/session.raw.log +**/*.session.log +**/*.raw.log + +# Editor / temp +**/*.tmp +**/*.bak +**/*.swp +``` + +5. **创建 `.context/.gitattributes`**： + +``` +# JSONL append-only: 'union' merge reduces conflicts +history/commits.jsonl merge=union +history/archives/*.jsonl merge=union +``` + +6. **创建 `.context/prefs/coding-style.md`**（团队编码规范模板）： + +```markdown +# Coding Style Guide + +> 此文件定义团队编码规范，所有 LLM 工具在修改代码时必须遵守。 +> 提交到 Git，团队共享。 + +## General +- Prefer small, reviewable changes; avoid unrelated refactors. +- Keep functions short (<50 lines); avoid deep nesting (≤3 levels). +- Name things explicitly; no single-letter variables except loop counters. +- Handle errors explicitly; never swallow errors silently. + +## Language-Specific + + + + +## Git Commits +- Conventional Commits, imperative mood. +- Atomic commits: one logical change per commit. + +## Testing +- Every feat/fix MUST include corresponding tests. +- Coverage must not decrease. +- Fix flow: write failing test FIRST, then fix code. + +## Security +- Never log secrets (tokens/keys/cookies/JWT). +- Validate inputs at trust boundaries. +``` + +7. **创建 `.context/prefs/workflow.md`**（LLM 工作流规则）： + +```markdown +# Development Workflow Rules + +> 此文件定义 LLM 开发工作流的强制规则。 +> 所有 LLM 工具在执行任务时必须遵守，不可跳过任何步骤。 + +## Full Flow (MUST follow, no exceptions) + +### feat (新功能) +1. 理解需求，分析影响范围 +2. 读取现有代码，理解模式 +3. 编写实现代码 +4. 编写对应测试 +5. 运行测试，修复失败 +6. 更新文档（若 API 变更） +7. 自查 lint / type-check + +### fix (缺陷修复) +1. 复现问题，确认症状 +2. 定位根因 +3. 编写失败测试（先有红灯） +4. 修复代码 +5. 验证测试通过（变绿灯） +6. 回归测试 + +### refactor (重构) +1. 确保现有测试通过 +2. 小步重构，每步可验证 +3. 重构后测试必须全部通过 +4. 不改变外部行为 + +## Context Logging (决策记录) + +当你做出以下决策时，MUST 追加到 `.context/current/branches/<当前分支>/session.log`： + +1. **方案选择**：选 A 不选 B 时，记录原因 +2. **Bug 发现与修复**：根因 + 修复方法 + 教训 +3. **API/架构决策**：接口设计选择 +4. **放弃的方案**：为什么放弃 + +追加格式： + +## +**Decision**: <你选择了什么> +**Alternatives**: <被排除的方案> +**Reason**: <为什么> +**Risk**: <潜在风险> +``` + +8. **创建 `.context/history/commits.jsonl`**（空文件） + +9. **创建 `.context/history/commits.md`**（人类视图模板）： + +```markdown +# Commit Decision History + +> 此文件是 `commits.jsonl` 的人类可读视图，可由工具重生成。 +> Canonical store: `commits.jsonl` (JSONL, append-only) + +| Date | Context-Id | Commit | Summary | Decisions | Bugs | Risk | +|------|-----------|--------|---------|-----------|------|------| +``` + +10. **注入 CLAUDE.md 引用**（若项目存在 CLAUDE.md）： + +检测项目根目录是否有 `CLAUDE.md`，若有则在末尾追加： + +```markdown + +## .context 项目上下文 + +> 项目使用 `.context/` 管理开发决策上下文。 + +- 编码规范：`.context/prefs/coding-style.md` +- 工作流规则：`.context/prefs/workflow.md` +- 决策历史：`.context/history/commits.md` + +**规则**：修改代码前必读 prefs/，做决策时按 workflow.md 规则记录日志。 +``` + +11. 输出初始化结果摘要 + +--- + +### 子命令：log + +`[模式：记录]` + +1. 获取当前 Git 分支名：`git branch --show-current` +2. 确保 `.context/current/branches//` 目录存在 +3. 将 `` 以结构化格式追加到 `session.log`： + +```markdown +## + +``` + +--- + +### 子命令：show + +`[模式：查看]` + +1. 获取当前分支名 +2. 读取 `.context/current/branches//session.log` +3. 若不存在，提示 "当前分支暂无决策日志" +4. 输出内容 + +--- + +### 子命令：compress + +`[模式：压缩]` + +将 `session.log` 压缩为结构化 `uncommit.md`，供提交前审查。 + +1. 读取 `.context/current/branches//session.log` +2. 若为空，提示无内容可压缩 +3. **脱敏**：扫描并替换潜在敏感信息（token/key/password → `[REDACTED]`） +4. **结构化提取**：从日志中提取 decisions / bugs / alternatives +5. **生成 uncommit.md**： + +```markdown +# Pre-commit Summary: + +| Time | Summary | Decision | Method | Result & Bug | +|------|---------|----------|--------|--------------| +| ... | ... | ... | ... | ... | +``` + +6. 输出压缩结果供用户审查 +7. 提示用户：确认后可执行 `/ccg:commit` 提交 + +--- + +### 子命令：history + +`[模式：查看]` + +1. 读取 `.context/history/commits.md` +2. 若不存在，提示 "暂无历史记录，请先使用 /ccg:context init" +3. 输出内容 +4. 若用户指定文件路径，从 `commits.jsonl` 检索 `changes.files` 包含该路径的条目 + +--- + +### 子命令：squash + +`[模式：合并]` + +配合 `git squash` 使用，合并多条 ContextEntry。 + +1. 接收 Context-Id 列表 +2. 从 `commits.jsonl` 读取对应条目 +3. 生成新的聚合 ContextEntry： + - 新 `context_id`（UUIDv7） + - `Context-Refs` = 所有被 squash 的 ids + - 合并 decisions / bugs / changes +4. 追加到 `commits.jsonl` +5. 重生成 `commits.md` + +--- + +## ContextEntry Schema (v1.0.0) + +每条 JSONL 记录格式： + +```json +{ + "schema_version": "1.0.0", + "context_id": "", + "created_at": "", + "producer": { + "tool": "", + "llm": { "provider": "", "model": "" } + }, + "git": { + "branch": "", + "commit_sha": "", + "trailers": { "Context-Id": "" } + }, + "summary": "", + "decisions": [{ + "title": "", + "rationale": "", + "tradeoffs": [""], + "assumptions": [""], + "rejected_alternatives": [{ "option": "", "reason": "" }], + "side_effects": [""] + }], + "bugs": [{ + "symptom": "", + "root_cause": "", + "fix": "", + "lesson": "" + }], + "changes": { "files": [""] }, + "tests": [{ "command": "", "result": "", "coverage": "" }], + "privacy": { "classification": "internal", "redactions_applied": true } +} +``` + +--- + +## 关键规则 + +1. **prefs/ 提交到 Git** — 团队共享编码规范 +2. **current/ 永不提交** — 原始日志仅本地 +3. **history/ 提交到 Git** — 永久决策归档 +4. **commits.jsonl 是 canonical** — commits.md 可重生成 +5. **UUIDv7 为主键** — 不依赖 commit SHA（rebase-safe） +6. **merge=union** — JSONL append 冲突自动合并 +7. **脱敏先于一切** — 任何写入 history 前必须脱敏 diff --git a/templates/prompts/codex/analyzer.md b/templates/prompts/codex/analyzer.md index 732a551..1d3757b 100644 --- a/templates/prompts/codex/analyzer.md +++ b/templates/prompts/codex/analyzer.md @@ -48,3 +48,11 @@ You are a senior technical analyst specializing in architecture evaluation, solu 3. **Options** - Alternative approaches with pros/cons 4. **Recommendation** - Preferred approach with rationale 5. **Action Items** - Concrete next steps + +## .context Awareness + +If the project has a `.context/` directory: +1. Read `.context/prefs/coding-style.md` and `.context/prefs/workflow.md` before analysis +2. Use rules from prefs/ as evaluation criteria +3. When analyzing, check `.context/history/commits.jsonl` for related past decisions +4. Document your key decisions and trade-offs clearly in your output (they will be captured for future context) diff --git a/templates/prompts/codex/architect.md b/templates/prompts/codex/architect.md index fbd6053..c27afb7 100644 --- a/templates/prompts/codex/architect.md +++ b/templates/prompts/codex/architect.md @@ -44,3 +44,11 @@ You are a senior backend architect specializing in scalable API design, database 2. **Architecture Decision** - Key design choices with rationale 3. **Implementation** - Unified Diff Patch 4. **Considerations** - Performance, security, scaling notes + +## .context Awareness + +If the project has a `.context/` directory: +1. Read `.context/prefs/coding-style.md` and `.context/prefs/workflow.md` before designing +2. Follow all coding conventions defined in prefs/ +3. Check `.context/history/commits.jsonl` for past architectural decisions on related modules +4. In your Architecture Decision section, clearly state: rationale, rejected alternatives, assumptions, and potential side effects (these will be captured as ContextEntry for future reference) diff --git a/templates/prompts/codex/debugger.md b/templates/prompts/codex/debugger.md index 4e1c4f1..5b17ec4 100644 --- a/templates/prompts/codex/debugger.md +++ b/templates/prompts/codex/debugger.md @@ -64,3 +64,11 @@ You are a senior debugging specialist focusing on backend systems, API issues, d ### Probable Root Cause [Conclusion with reasoning] ``` + +## .context Awareness + +If the project has a `.context/` directory: +1. Read `.context/prefs/workflow.md` for project-specific debugging rules +2. Check `.context/history/commits.jsonl` for past bugs on related files — search `bugs[]` and `changes.files` fields +3. Past decision context (assumptions, rejected alternatives) may reveal why code was written a certain way +4. Document your diagnosis clearly: symptom, root cause, fix, and lesson learned (will be captured for future context) diff --git a/templates/prompts/codex/optimizer.md b/templates/prompts/codex/optimizer.md index 19bf4cb..8074ebc 100644 --- a/templates/prompts/codex/optimizer.md +++ b/templates/prompts/codex/optimizer.md @@ -72,3 +72,10 @@ You are a senior performance engineer specializing in backend optimization, data - Expected After: [metrics] - How to measure: [commands/tools] ``` + +## .context Awareness + +If the project has a `.context/` directory: +1. Read `.context/prefs/coding-style.md` for project performance conventions +2. Check `.context/history/commits.jsonl` for past optimization decisions — avoid re-doing work or reverting previous optimizations without reason +3. Document optimization trade-offs clearly in your output (will be captured for future context) diff --git a/templates/prompts/codex/reviewer.md b/templates/prompts/codex/reviewer.md index 6a17a47..58af19a 100644 --- a/templates/prompts/codex/reviewer.md +++ b/templates/prompts/codex/reviewer.md @@ -64,3 +64,10 @@ RECOMMENDATION: [PASS/NEEDS_IMPROVEMENT] 2. **Critical Issues** - Must fix before merge 3. **Suggestions** - Nice to have improvements 4. **Positive Notes** - What's done well + +## .context Awareness + +If the project has a `.context/` directory: +1. Read `.context/prefs/coding-style.md` as the primary review standard +2. Read `.context/prefs/workflow.md` to verify the full development flow was followed (tests written, docs updated, etc.) +3. Check `.context/history/commits.jsonl` for past decisions on the same files — flag if current changes contradict previous architectural decisions without justification diff --git a/templates/prompts/codex/tester.md b/templates/prompts/codex/tester.md index a01edae..2ec0ce8 100644 --- a/templates/prompts/codex/tester.md +++ b/templates/prompts/codex/tester.md @@ -53,3 +53,10 @@ You are a senior test engineer specializing in backend testing, API testing, and 2. **Test Cases** - List of scenarios to cover 3. **Implementation** - Unified Diff Patch for test files 4. **Coverage Notes** - What's covered and what's not + +## .context Awareness + +If the project has a `.context/` directory: +1. Read `.context/prefs/coding-style.md` for testing conventions (naming, patterns, coverage requirements) +2. Read `.context/prefs/workflow.md` to understand required test flow (e.g., failing test first for bug fixes) +3. Check `.context/history/commits.jsonl` for past bugs on related files — ensure regression tests cover previously fixed issues diff --git a/templates/prompts/gemini/analyzer.md b/templates/prompts/gemini/analyzer.md index 8be3d53..864f003 100644 --- a/templates/prompts/gemini/analyzer.md +++ b/templates/prompts/gemini/analyzer.md @@ -51,3 +51,11 @@ You are a senior UI/UX analyst specializing in design systems, user experience e 3. **Technical Considerations** - Frontend architecture impact 4. **Options** - Alternative approaches with trade-offs 5. **Recommendation** - Preferred approach with rationale + +## .context Awareness + +If the project has a `.context/` directory: +1. Read `.context/prefs/coding-style.md` and `.context/prefs/workflow.md` before analysis +2. Use rules from prefs/ as evaluation criteria +3. When analyzing, check `.context/history/commits.jsonl` for related past decisions +4. Document your key decisions and trade-offs clearly in your output (they will be captured for future context) diff --git a/templates/prompts/gemini/architect.md b/templates/prompts/gemini/architect.md index 4bc99fc..ef9e7e2 100644 --- a/templates/prompts/gemini/architect.md +++ b/templates/prompts/gemini/architect.md @@ -45,3 +45,11 @@ You are a senior frontend architect specializing in UI/UX design systems, compon 2. **Architecture Decision** - Key design choices with rationale 3. **Implementation Plan** - Step-by-step with pseudo-code 4. **Considerations** - Performance, accessibility, maintainability notes + +## .context Awareness + +If the project has a `.context/` directory: +1. Read `.context/prefs/coding-style.md` and `.context/prefs/workflow.md` before designing +2. Follow all coding conventions defined in prefs/ +3. Check `.context/history/commits.jsonl` for past architectural decisions on related components +4. In your Architecture Decision section, clearly state: rationale, rejected alternatives, assumptions, and potential side effects (these will be captured as ContextEntry for future reference) diff --git a/templates/prompts/gemini/debugger.md b/templates/prompts/gemini/debugger.md index 5ba49cf..7067f67 100644 --- a/templates/prompts/gemini/debugger.md +++ b/templates/prompts/gemini/debugger.md @@ -68,3 +68,11 @@ You are a senior frontend debugging specialist focusing on UI issues, component ### Probable Root Cause [Conclusion with reasoning] ``` + +## .context Awareness + +If the project has a `.context/` directory: +1. Read `.context/prefs/workflow.md` for project-specific debugging rules +2. Check `.context/history/commits.jsonl` for past bugs on related components — search `bugs[]` and `changes.files` fields +3. Past decision context (assumptions, rejected alternatives) may reveal why UI was built a certain way +4. Document your diagnosis clearly: symptom, root cause, fix, and lesson learned (will be captured for future context) diff --git a/templates/prompts/gemini/frontend.md b/templates/prompts/gemini/frontend.md index f4e118c..3b92eb0 100644 --- a/templates/prompts/gemini/frontend.md +++ b/templates/prompts/gemini/frontend.md @@ -54,3 +54,11 @@ You are a senior frontend developer specializing in React applications, responsi 2. **Design Decisions** - UI/UX choices with rationale 3. **Implementation** - Unified Diff Patch 4. **Usage Example** - How to use the component + +## .context Awareness + +If the project has a `.context/` directory: +1. Read `.context/prefs/coding-style.md` and `.context/prefs/workflow.md` before coding +2. Follow all conventions (naming, patterns, testing requirements) +3. When making design decisions (choosing component patterns, state management, etc.), clearly state rationale and rejected alternatives in your output +4. Follow the full development flow from workflow.md (implement → test → docs) diff --git a/templates/prompts/gemini/optimizer.md b/templates/prompts/gemini/optimizer.md index 3d9f254..7c068b2 100644 --- a/templates/prompts/gemini/optimizer.md +++ b/templates/prompts/gemini/optimizer.md @@ -75,3 +75,10 @@ You are a senior frontend performance engineer specializing in React optimizatio - Expected after: [score] - How to measure: [tools] ``` + +## .context Awareness + +If the project has a `.context/` directory: +1. Read `.context/prefs/coding-style.md` for project performance conventions +2. Check `.context/history/commits.jsonl` for past optimization decisions — avoid re-doing work or reverting previous optimizations without reason +3. Document optimization trade-offs clearly in your output (will be captured for future context) diff --git a/templates/prompts/gemini/reviewer.md b/templates/prompts/gemini/reviewer.md index 88528e3..068485b 100644 --- a/templates/prompts/gemini/reviewer.md +++ b/templates/prompts/gemini/reviewer.md @@ -71,3 +71,10 @@ RECOMMENDATION: [PASS/NEEDS_IMPROVEMENT] 3. **Design Issues** - Inconsistencies 4. **Suggestions** - Improvements 5. **Positive Notes** - What's done well + +## .context Awareness + +If the project has a `.context/` directory: +1. Read `.context/prefs/coding-style.md` as the primary review standard +2. Read `.context/prefs/workflow.md` to verify the full development flow was followed (tests written, docs updated, etc.) +3. Check `.context/history/commits.jsonl` for past decisions on the same components — flag if current changes contradict previous design decisions without justification diff --git a/templates/prompts/gemini/tester.md b/templates/prompts/gemini/tester.md index 9169b7c..21b01e1 100644 --- a/templates/prompts/gemini/tester.md +++ b/templates/prompts/gemini/tester.md @@ -59,3 +59,10 @@ You are a senior test engineer specializing in frontend testing, component testi 2. **Test Cases** - Scenarios to cover 3. **Implementation** - Unified Diff Patch for test files 4. **Accessibility Notes** - a11y test coverage + +## .context Awareness + +If the project has a `.context/` directory: +1. Read `.context/prefs/coding-style.md` for testing conventions (naming, patterns, coverage requirements) +2. Read `.context/prefs/workflow.md` to understand required test flow (e.g., failing test first for bug fixes) +3. Check `.context/history/commits.jsonl` for past bugs on related components — ensure regression tests cover previously fixed issues diff --git a/templates/rules/ccg-skills.md b/templates/rules/ccg-skills.md new file mode 100644 index 0000000..edac140 --- /dev/null +++ b/templates/rules/ccg-skills.md @@ -0,0 +1,63 @@ +# CCG Quality Gates — Auto-trigger Rules + +When working in a project, automatically invoke the corresponding quality gate skills based on the scenario below. These skills are installed at `~/.claude/skills/ccg/` and can be called directly. + +## Trigger Rules + +### New Module Created + +When a new module/package/directory is created with source code: + +``` +/gen-docs → Generate README.md + DESIGN.md skeleton + ↓ (after development) +/verify-module → Check structure completeness + ↓ +/verify-security → Scan for security vulnerabilities +``` + +### Code Changes > 30 Lines + +When a single task produces code changes exceeding 30 lines: + +``` +/verify-change → Analyze change impact, check doc sync + ↓ +/verify-quality → Check complexity, code smells, naming +``` + +### Security-Related Changes + +When changes involve authentication, authorization, encryption, input validation, or secrets management: + +``` +/verify-security → Scan for vulnerabilities +``` + +### Refactoring + +When refactoring existing code: + +``` +/verify-change → Ensure docs reflect the refactoring + ↓ +/verify-quality → Verify quality improved + ↓ +/verify-security → No new vulnerabilities introduced +``` + +## Execution Rules + +1. **Non-blocking** — Quality gates produce reports but do NOT block delivery unless Critical issues are found +2. **Chainable** — Run gates in the order specified above; skip if previous gate fails +3. **Silent on pass** — Only report findings; do not output "all clear" messages for every gate +4. **Critical = must fix** — Only `Critical` / `High` severity findings require action before delivery +5. **Idempotent** — Safe to re-run; same input produces same output + +## Multi-Agent Coordination + +When a task involves 3+ independent files/modules or 2+ parallel workflows, refer to the multi-agent orchestration skill at `~/.claude/skills/ccg/orchestration/multi-agent/SKILL.md` for: + +- Agent role assignment (Lead / Scout / Worker / Soldier / Drone) +- File ownership locking (one writer per file at any time) +- Task decomposition strategy (by file, by module, or by pipeline)