From 4d483fd9cb6b06b56706943c6fe090fd8275e362 Mon Sep 17 00:00:00 2001 From: 7fpb5574ck-maker <369284625@qq.com> Date: Sun, 26 Apr 2026 23:18:54 +0800 Subject: [PATCH 1/4] chore: add SECURITY.md and CODE_OF_CONDUCT.md Made-with: Cursor --- CODE_OF_CONDUCT.md | 77 ++++++++++++++++++++++++++++++++++++++++++++++ SECURITY.md | 14 +++++++++ 2 files changed, 91 insertions(+) create mode 100644 CODE_OF_CONDUCT.md create mode 100644 SECURITY.md diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md new file mode 100644 index 0000000..8faed83 --- /dev/null +++ b/CODE_OF_CONDUCT.md @@ -0,0 +1,77 @@ +# Contributor Covenant Code of Conduct + +## Our Pledge + +We as members, contributors, and leaders pledge to make participation in our community a harassment-free experience for everyone, regardless of age, body size, visible or invisible disability, ethnicity, sex characteristics, gender identity and expression, level of experience, education, socio-economic status, nationality, personal appearance, race, caste, color, religion, or sexual identity and orientation. + +We pledge to act and interact in ways that contribute to an open, welcoming, diverse, inclusive, and healthy community. + +## Our Standards + +Examples of behavior that contributes to a positive environment for our community include: + +* Demonstrating empathy and kindness toward other people +* Being respectful of differing opinions, viewpoints, and experiences +* Giving and gracefully accepting constructive feedback +* Accepting responsibility and apologizing to those affected by our mistakes, and learning from the experience +* Focusing on what is best not just for us as individuals, but for the overall community + +Examples of unacceptable behavior include: + +* The use of sexualized language or imagery, and sexual attention or advances of any kind +* Trolling, insulting or derogatory comments, and personal or political attacks +* Public or private harassment +* Publishing others' private information, such as a physical or email address, without their explicit permission +* Other conduct which could reasonably be considered inappropriate in a professional setting + +## Enforcement Responsibilities + +Community leaders are responsible for clarifying and enforcing our standards of acceptable behavior and will take appropriate and fair corrective action in response to any behavior that they deem inappropriate, threatening, offensive, or harmful. + +Community leaders have the right and responsibility to remove, edit, or reject comments, commits, code, wiki edits, issues, and other contributions that are not aligned to this Code of Conduct, and will communicate reasons for moderation decisions when appropriate. + +## Scope + +This Code of Conduct applies within all community spaces, and also applies when an individual is officially representing the community in public spaces. Examples of representing our community include using an official e-mail address, posting via an official social media account, or acting as an appointed representative at an online or offline event. + +## Enforcement + +Instances of abusive, harassing, or otherwise unacceptable behavior may be reported to the community leaders responsible for enforcement at the repository maintainers (see the repository README for a contact method if one is provided). You may also use GitHub reporting features where available. All complaints will be reviewed and investigated promptly and fairly. + +All community leaders are obligated to respect the privacy and security of the reporter of any incident. + +## Enforcement Guidelines + +Community leaders will follow these Community Impact Guidelines in determining the consequences for any action they deem in violation of this Code of Conduct: + +### 1. Correction + +**Community Impact**: Use of inappropriate language or other behavior deemed unprofessional or unwelcome in the community. + +**Consequence**: A private, written warning from community leaders, providing clarity around the nature of the violation and an explanation of why the behavior was inappropriate. A public apology may be requested. + +### 2. Warning + +**Community Impact**: A violation through a single incident or series of actions. + +**Consequence**: A warning with consequences for continued behavior. No interaction with the people involved, including unsolicited interaction with those enforcing the Code of Conduct, for a specified period of time. This includes avoiding interactions in community spaces as well as external channels like social media. Violating these terms may lead to a temporary or permanent ban. + +### 3. Temporary Ban + +**Community Impact**: A serious violation of community standards, including sustained inappropriate behavior. + +**Consequence**: A temporary ban from any sort of interaction or public communication with the community for a specified period of time. No public or private interaction with the people involved, including unsolicited interaction with those enforcing the Code of Conduct, is allowed during this period. Violating these terms may lead to a permanent ban. + +### 4. Permanent Ban + +**Community Impact**: Demonstrating a pattern of violation of community standards, including sustained inappropriate behavior, harassment of an individual, or aggression toward or disparagement of classes of individuals. + +**Consequence**: A permanent ban from any sort of public interaction within the community. + +## Attribution + +This Code of Conduct is adapted from the [Contributor Covenant](https://www.contributor-covenant.org/), version 2.1, available at . + +Community Impact Guidelines were inspired by [Mozilla's code of conduct enforcement ladder](https://github.com/mozilla/diversity). + +For answers to common questions about this code of conduct, see the [FAQ](https://www.contributor-covenant.org/faq). Translations are [available](https://www.contributor-covenant.org/translations). diff --git a/SECURITY.md b/SECURITY.md new file mode 100644 index 0000000..34ea560 --- /dev/null +++ b/SECURITY.md @@ -0,0 +1,14 @@ +# Security Policy + +## Supported versions + +The maintainers may provide security fixes for the default branch and recent tagged or released versions, as described in the repository README. If you depend on an older branch or fork, open an issue to ask about support. + +## Reporting a vulnerability + +**Please do not report security vulnerabilities through public GitHub issues.** + +- If the repository has [GitHub private vulnerability reporting](https://docs.github.com/en/code-security/security-advisories/guidance-on-reporting-and-writing/privately-reporting-a-security-vulnerability) enabled, use the **Report a vulnerability** link on the **Security** tab. +- Otherwise, contact the maintainers through a private channel (for example, a security contact email in the repository README, if one is listed). + +We aim to acknowledge valid reports in a reasonable time and coordinate remediation and disclosure with you. From b8e0bd4f8d8866ad5bc0f972d47bdb186d27515b Mon Sep 17 00:00:00 2001 From: 7fpb5574ck-maker <369284625@qq.com> Date: Sun, 26 Apr 2026 23:32:31 +0800 Subject: [PATCH 2/4] chore: add root config files Made-with: Cursor --- .editorconfig | 15 +++++++++++++++ .gitignore | 25 +++++++++++++++++++++++++ 2 files changed, 40 insertions(+) create mode 100644 .editorconfig create mode 100644 .gitignore diff --git a/.editorconfig b/.editorconfig new file mode 100644 index 0000000..3808454 --- /dev/null +++ b/.editorconfig @@ -0,0 +1,15 @@ +root = true + +[*] +charset = utf-8 +end_of_line = lf +insert_final_newline = true +trim_trailing_whitespace = true +indent_style = space +indent_size = 2 + +[*.md] +trim_trailing_whitespace = false + +[*.{py,toml}] +indent_size = 4 diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..2d25584 --- /dev/null +++ b/.gitignore @@ -0,0 +1,25 @@ +# OS / editor +.DS_Store +*.log +.env +.env.* +!.env.example +.idea/ +.vscode/ + +# JavaScript / Node +node_modules/ +dist/ +build/ +.cache/ + +# Python +__pycache__/ +*.py[cod] +.pytest_cache/ +.mypy_cache/ +.ruff_cache/ +.coverage +htmlcov/ +.venv/ +venv/ From 279202583d9d0fb6d517fec959ab714511a97f74 Mon Sep 17 00:00:00 2001 From: 7fpb5574ck-maker <369284625@qq.com> Date: Sun, 26 Apr 2026 23:48:43 +0800 Subject: [PATCH 3/4] docs: bilingual readme Made-with: Cursor --- README.en.md | 239 +++++++++++++++++++++++++++++++++++++++++++++++ README.md | 257 ++++++++++++++++++++++----------------------------- 2 files changed, 347 insertions(+), 149 deletions(-) create mode 100644 README.en.md diff --git a/README.en.md b/README.en.md new file mode 100644 index 0000000..d375f91 --- /dev/null +++ b/README.en.md @@ -0,0 +1,239 @@ +# Claude Code Workflow + +**English** | [中文](README.md) + +A battle-tested workflow template for Claude Code — memory management, context engineering, and task routing distilled from daily usage across multiple projects. + +**Not a tutorial. Not a toy config. A production workflow that actually ships.** + +> **What's new in v2**: ~50 days of real-world iteration since v1. Key additions: a PreToolUse Hook layer (rules enforced at tool-call time, not just at session start), Plan Gating for complex tasks, a mandatory Subagent dispatch checklist (backed by 30 days of routing data), and 10 P0 rules rewritten as event-driven hard rules instead of abstract principles. Full notes → [CHANGELOG.md](./CHANGELOG.md). + +## Why This Exists + +Claude Code is powerful out of the box, but without structure it becomes a smart assistant that forgets everything between sessions. This template turns it into a **persistent, self-improving development partner** that: + +- Remembers past mistakes and applies lessons automatically +- Manages context across long sessions without drifting +- Routes tasks to the right model tier (Opus/Sonnet/Haiku/Codex/Local) +- Forces verification before claiming completion (no more "should work now") +- Auto-saves progress so closing the window doesn't lose work + +## Architecture: Three Layers + +``` +┌─────────────────────────────────────────────────────────┐ +│ Layer 0: Auto-loaded Rules (always in context) │ +│ ┌─────────────┐ ┌────────────┐ ┌───────────────┐ │ +│ │ behaviors.md │ │skill- │ │memory-flush.md│ │ +│ │ │ │triggers.md │ │ │ │ +│ └─────────────┘ └────────────┘ └───────────────┘ │ +├─────────────────────────────────────────────────────────┤ +│ Layer 1: On-demand Docs (loaded when needed) │ +│ agents.md · content-safety.md · task-routing.md │ +│ behaviors-extended.md · scaffolding-checkpoint.md ... │ +├─────────────────────────────────────────────────────────┤ +│ Layer 2: Hot Data (your working memory) │ +│ today.md · projects.md · goals.md · active-tasks.json │ +└─────────────────────────────────────────────────────────┘ +``` + +**Why three layers?** Context window is expensive. Loading everything wastes tokens and degrades quality. This system loads rules always (~2K tokens), docs only when relevant (~1-3K each), and keeps your daily state hot for instant recall. + +## What's Inside + +``` +claude-code-workflow/ +├── CLAUDE.md # Entry point — Claude reads this first +├── README.md # You are here +│ +├── rules/ # Layer 0: Always loaded +│ ├── behaviors.md # Core behavior rules (debugging, commits, routing) +│ ├── skill-triggers.md # When to auto-invoke which skill +│ └── memory-flush.md # Auto-save triggers (never lose progress) +│ +├── docs/ # Layer 1: On-demand reference +│ ├── agents.md # Multi-model collaboration framework +│ ├── behaviors-extended.md # Extended rules (knowledge base, associations) +│ ├── behaviors-reference.md # Detailed operation guides +│ ├── content-safety.md # AI hallucination prevention system +│ ├── scaffolding-checkpoint.md # "Do you really need to self-host?" checklist +│ └── task-routing.md # Model tier routing + cost comparison +│ +├── memory/ # Layer 2: Your working state (templates) +│ ├── today.md # Daily session log +│ ├── projects.md # Cross-project status overview +│ ├── goals.md # Week/month/quarter goals +│ └── active-tasks.json # Cross-session task registry +│ +├── skills/ # Reusable skill definitions +│ ├── session-end/SKILL.md # Auto wrap-up: save progress + commit + record +│ ├── verification-before-completion/SKILL.md # "Run the test. Read the output. THEN claim." +│ ├── systematic-debugging/SKILL.md # 5-phase debugging (recall → root cause → fix) +│ ├── planning-with-files/SKILL.md # File-based planning for complex tasks +│ └── experience-evolution/SKILL.md # Auto-accumulate project knowledge +│ +├── agents/ # Custom agent definitions +│ ├── pr-reviewer.md # Code review agent +│ ├── security-reviewer.md # OWASP security scanning agent +│ └── performance-analyzer.md # Performance bottleneck analysis agent +│ +└── commands/ # Custom slash commands + ├── debug.md # /debug — Start systematic debugging + ├── deploy.md # /deploy — Pre-deployment checklist + ├── exploration.md # /exploration — CTO challenge before coding + └── review.md # /review — Prepare code review +``` + +## Quick Start + +### 1. Copy to your Claude Code config + +```bash +# Clone the template +git clone https://github.com/runesleo/claude-code-workflow.git + +# Copy to your Claude Code config directory +cp -r claude-code-workflow/* ~/.claude/ + +# Or symlink if you want to keep it as a git repo +ln -sf ~/claude-code-workflow/rules ~/.claude/rules +ln -sf ~/claude-code-workflow/docs ~/.claude/docs +# ... etc +``` + +### 2. Customize CLAUDE.md + +Open `~/.claude/CLAUDE.md` and fill in: + +- **User Info**: Your name, project directory, social handles +- **Sub-project Memory Routes**: Map your projects to memory paths +- **SSOT Ownership Table**: Define where each type of info lives +- **On-demand Loading Index**: Adjust doc paths if needed + +### 3. Start a session + +```bash +claude +``` + +Claude will automatically load your rules and start following the workflow. Try: + +- Start coding and notice the **task routing** ("🔀 Route: bug fix → Sonnet") +- Hit a bug and watch **systematic debugging** kick in +- Say "that's all for now" and see **session-end** auto-save everything +- Come back tomorrow and find your context preserved in `today.md` + +## Key Concepts + +### SSOT (Single Source of Truth) + +Every piece of information has ONE canonical location. The SSOT table in CLAUDE.md maps info types to files. Claude is trained to check SSOT before writing, preventing the "same info in 5 places, all outdated" problem. + +### Memory Flush + +Claude auto-saves progress on every task completion, every commit, and every exit signal. You can close the window mid-sentence and nothing is lost. No more "I forgot to save my context." + +### Verification Before Completion + +The most impactful rule: Claude cannot claim work is done without running the verification command and reading the output. Eliminates the #1 AI coding failure mode — "should work now" without actually checking. + +### Three-Tier Task Routing + +Not every task needs Opus. The routing system automatically matches task complexity to model tier: +- **Opus**: Critical logic, security-sensitive, complex reasoning +- **Sonnet**: Daily development, analysis, most coding tasks +- **Haiku**: Simple queries, subagent tasks, quick lookups +- **Codex**: Cross-verification, code review, second opinions +- **Local**: Commit messages, formatting, offline work + +### Sunday Rule + +System optimization happens on Sundays. On other days, if you try to tweak your workflow instead of shipping, Claude will intercept and remind you to focus on output. Configurable to any cadence you prefer. + +## Customization Guide + +### Adding a new project + +1. Add to `memory/projects.md` +2. Add memory route in CLAUDE.md's "Sub-project Memory Routes" +3. Create `PROJECT_CONTEXT.md` in the project root + +### Adding a new skill + +Create `skills/your-skill/SKILL.md` with: + +```yaml +--- +name: your-skill +description: What it does +allowed-tools: + - Read + - Write + - Bash +--- + +# Your Skill + +[Instructions for Claude when this skill is invoked] +``` + +### Adding a new agent + +Create `agents/your-agent.md` with: + +```yaml +--- +name: your-agent +description: What it does +tools: Read, Grep, Glob, Bash +--- + +# Your Agent + +[Agent personality, review dimensions, output format] +``` + +### Adjusting model routing + +Edit `rules/behaviors.md` → "Task Routing" section, and `docs/task-routing.md` for detailed tier definitions. + +## Philosophy + +This template encodes several principles learned from daily AI-assisted development: + +1. **Structure > Prompting**: A well-organized config file beats clever one-off prompts every time. +2. **Memory > Intelligence**: An AI that remembers your past mistakes is more valuable than a smarter AI that starts fresh each session. +3. **Verification > Confidence**: The cost of running `npm test` is always less than the cost of shipping a broken build. +4. **Layered Loading > Flat Config**: Don't dump everything into context. Load rules always, docs on demand, data when needed. +5. **Auto-save > Manual Save**: If it requires the user to remember, it will be forgotten. Make it automatic. + +## Requirements + +- [Claude Code](https://docs.anthropic.com/en/docs/claude-code) CLI (Claude Max or API subscription) +- Optional: Codex CLI for cross-verification +- Optional: Ollama for local model fallback + +## Prior Art & Credits + +This template draws from: +- [Manus](https://manus.im/) file-based planning approach +- OWASP Top 10 for security review patterns +- Real-world experience from building [x-reader](https://github.com/runesleo/x-reader) (650+ stars) and other open-source projects + +## Star History + +[![Star History Chart](https://api.star-history.com/svg?repos=runesleo/claude-code-workflow&type=Date)](https://star-history.com/#runesleo/claude-code-workflow&Date) + +## License + +MIT — Use it, fork it, make it yours. + +## About the author + +*Leo ([@runes_leo](https://x.com/runes_leo)) — AI × Crypto independent builder. Trading on [Polymarket](https://polymarket.com/?r=githuball&via=runes-leo&utm_source=github&utm_content=claude-code-workflow), building data and trading systems with Claude Code and Codex.* + +[leolabs.me](https://leolabs.me) — writing · community · open-source tools · indie projects · all platforms. + +[X Subscription](https://x.com/runes_leo/creator-subscriptions/subscribe) — paid content weekly, or just buy me a coffee 😁 + +*Learn in public, Build in public.* diff --git a/README.md b/README.md index 8c9df3c..d2e34da 100644 --- a/README.md +++ b/README.md @@ -1,237 +1,196 @@ -# Claude Code Workflow +# Claude Code 工作流 -A battle-tested workflow template for Claude Code — memory management, context engineering, and task routing distilled from daily usage across multiple projects. +[English](README.en.md) | **中文** -**Not a tutorial. Not a toy config. A production workflow that actually ships.** +从多项目日常使用中提炼的 Claude Code 工作流模板——涵盖记忆管理、上下文工程与任务路由。 -> **What's new in v2**: ~50 days of real-world iteration since v1. Key additions: a PreToolUse Hook layer (rules enforced at tool-call time, not just at session start), Plan Gating for complex tasks, a mandatory Subagent dispatch checklist (backed by 30 days of routing data), and 10 P0 rules rewritten as event-driven hard rules instead of abstract principles. Full notes → [CHANGELOG.md](./CHANGELOG.md). +**不是教程、不是玩具配置。这是一套能真正上线交付的产线工作流。** -## Why This Exists +> **v2 新特性**：相对 v1 已迭代约 50 天。新增：PreToolUse Hook 层（在工具调用时强制执行规则，而不仅是会话开头）、复杂任务的计划门禁、强制子 Agent 分派检查清单（基于 30 天路由数据），以及将 10 条 P0 规则改写为事件驱动硬规则。完整说明见 [CHANGELOG.md](./CHANGELOG.md)。 -Claude Code is powerful out of the box, but without structure it becomes a smart assistant that forgets everything between sessions. This template turns it into a **persistent, self-improving development partner** that: +## 为什么需要它 -- Remembers past mistakes and applies lessons automatically -- Manages context across long sessions without drifting -- Routes tasks to the right model tier (Opus/Sonnet/Haiku/Codex/Local) -- Forces verification before claiming completion (no more "should work now") -- Auto-saves progress so closing the window doesn't lose work +Claude Code 本身很强，但没有结构时，很容易变成「会话一断就忘光」的聪明助手。本模板把它变成**可持续、会自我改进的开发搭档**，能： -## Architecture: Three Layers +- 记住过去的错误并自动应用教训 +- 在长会话中管理上下文、减少漂移 +- 将任务路由到合适档位（Opus / Sonnet / Haiku / Codex / Local） +- 在宣称完成前强制验证（告别「应该好了吧」） +- 自动保存进度，关窗也不丢活 + +## 架构：三层 ``` ┌─────────────────────────────────────────────────────────┐ -│ Layer 0: Auto-loaded Rules (always in context) │ +│ Layer 0: 自动加载规则（始终驻留上下文） │ │ ┌─────────────┐ ┌────────────┐ ┌───────────────┐ │ │ │ behaviors.md │ │skill- │ │memory-flush.md│ │ │ │ │ │triggers.md │ │ │ │ │ └─────────────┘ └────────────┘ └───────────────┘ │ ├─────────────────────────────────────────────────────────┤ -│ Layer 1: On-demand Docs (loaded when needed) │ +│ Layer 1: 按需文档（需要时加载） │ │ agents.md · content-safety.md · task-routing.md │ -│ behaviors-extended.md · scaffolding-checkpoint.md ... │ +│ behaviors-extended.md · scaffolding-checkpoint.md ... │ ├─────────────────────────────────────────────────────────┤ -│ Layer 2: Hot Data (your working memory) │ -│ today.md · projects.md · goals.md · active-tasks.json │ +│ Layer 2: 热数据（你的工作记忆） │ +│ today.md · projects.md · goals.md · active-tasks.json │ └─────────────────────────────────────────────────────────┘ ``` -**Why three layers?** Context window is expensive. Loading everything wastes tokens and degrades quality. This system loads rules always (~2K tokens), docs only when relevant (~1-3K each), and keeps your daily state hot for instant recall. +**为什么分三层？** 上下文成本很高。全量塞入会浪费 token、拉低质量。本设计：始终加载规则（约 2K token）、仅按需读文档（各约 1–3K）、日常状态常热、随取随用。 -## What's Inside +## 内容结构 ``` claude-code-workflow/ -├── CLAUDE.md # Entry point — Claude reads this first -├── README.md # You are here +├── CLAUDE.md # 入口，Claude 先读 +├── README.md # 你在这里 │ -├── rules/ # Layer 0: Always loaded -│ ├── behaviors.md # Core behavior rules (debugging, commits, routing) -│ ├── skill-triggers.md # When to auto-invoke which skill -│ └── memory-flush.md # Auto-save triggers (never lose progress) +├── rules/ # Layer 0：常载 +│ ├── behaviors.md # 行为规则（排错、提交、路由） +│ ├── skill-triggers.md # 自动触发 skill 条件 +│ └── memory-flush.md # 自动保存（避免丢进度） │ -├── docs/ # Layer 1: On-demand reference -│ ├── agents.md # Multi-model collaboration framework -│ ├── behaviors-extended.md # Extended rules (knowledge base, associations) -│ ├── behaviors-reference.md # Detailed operation guides -│ ├── content-safety.md # AI hallucination prevention system -│ ├── scaffolding-checkpoint.md # "Do you really need to self-host?" checklist -│ └── task-routing.md # Model tier routing + cost comparison +├── docs/ # Layer 1：按需 +│ ├── agents.md # 多模型协作框架 +│ ├── behaviors-extended.md # 拓展规则 +│ ├── behaviors-reference.md # 操作细则 +│ ├── content-safety.md # 防幻觉 +│ ├── scaffolding-checkpoint.md # 自建前检清单 +│ └── task-routing.md # 模型档位与成本 │ -├── memory/ # Layer 2: Your working state (templates) -│ ├── today.md # Daily session log -│ ├── projects.md # Cross-project status overview -│ ├── goals.md # Week/month/quarter goals -│ └── active-tasks.json # Cross-session task registry +├── memory/ # Layer 2：工作态模板 +│ ├── today.md +│ ├── projects.md +│ ├── goals.md +│ └── active-tasks.json │ -├── skills/ # Reusable skill definitions -│ ├── session-end/SKILL.md # Auto wrap-up: save progress + commit + record -│ ├── verification-before-completion/SKILL.md # "Run the test. Read the output. THEN claim." -│ ├── systematic-debugging/SKILL.md # 5-phase debugging (recall → root cause → fix) -│ ├── planning-with-files/SKILL.md # File-based planning for complex tasks -│ └── experience-evolution/SKILL.md # Auto-accumulate project knowledge +├── skills/ +│ ├── session-end/SKILL.md +│ ├── verification-before-completion/SKILL.md +│ ├── systematic-debugging/SKILL.md +│ ├── planning-with-files/SKILL.md +│ └── experience-evolution/SKILL.md │ -├── agents/ # Custom agent definitions -│ ├── pr-reviewer.md # Code review agent -│ ├── security-reviewer.md # OWASP security scanning agent -│ └── performance-analyzer.md # Performance bottleneck analysis agent +├── agents/ +│ ├── pr-reviewer.md +│ ├── security-reviewer.md +│ └── performance-analyzer.md │ -└── commands/ # Custom slash commands - ├── debug.md # /debug — Start systematic debugging - ├── deploy.md # /deploy — Pre-deployment checklist - ├── exploration.md # /exploration — CTO challenge before coding - └── review.md # /review — Prepare code review +└── commands/ + ├── debug.md + ├── deploy.md + ├── exploration.md + └── review.md ``` -## Quick Start +## 快速开始 -### 1. Copy to your Claude Code config +### 1. 复制到 Claude Code 配置 ```bash -# Clone the template git clone https://github.com/runesleo/claude-code-workflow.git - -# Copy to your Claude Code config directory cp -r claude-code-workflow/* ~/.claude/ -# Or symlink if you want to keep it as a git repo +# 或符号链接 ln -sf ~/claude-code-workflow/rules ~/.claude/rules ln -sf ~/claude-code-workflow/docs ~/.claude/docs -# ... etc +# … ``` -### 2. Customize CLAUDE.md +### 2. 自定义 CLAUDE.md -Open `~/.claude/CLAUDE.md` and fill in: +打开 `~/.claude/CLAUDE.md`，补全： -- **User Info**: Your name, project directory, social handles -- **Sub-project Memory Routes**: Map your projects to memory paths -- **SSOT Ownership Table**: Define where each type of info lives -- **On-demand Loading Index**: Adjust doc paths if needed +- **用户信息**、主项目目录、社交 +- **子项目记忆路由** +- **SSOT 归属表**、各类型信息存放位置 +- **按需加载索引**（可调整 doc 路径） -### 3. Start a session +### 3. 启动会话 ```bash claude ``` -Claude will automatically load your rules and start following the workflow. Try: - -- Start coding and notice the **task routing** ("🔀 Route: bug fix → Sonnet") -- Hit a bug and watch **systematic debugging** kick in -- Say "that's all for now" and see **session-end** auto-save everything -- Come back tomorrow and find your context preserved in `today.md` +Claude 会加载规则并按工作流执行。可尝试：写代码时观察**任务路由**、遇到 bug 时看**系统化排错**、说收工看 **session-end** 自动保存、次日从 `today.md` 接上下文。 -## Key Concepts +## 关键概念 -### SSOT (Single Source of Truth) +### SSOT（单一事实源） -Every piece of information has ONE canonical location. The SSOT table in CLAUDE.md maps info types to files. Claude is trained to check SSOT before writing, preventing the "same info in 5 places, all outdated" problem. +每条信息有且仅有一个规范位置。`CLAUDE.md` 中的 SSOT 表将信息类型映射到文件，先查再写，避免五处各写一版、全部过期。 ### Memory Flush -Claude auto-saves progress on every task completion, every commit, and every exit signal. You can close the window mid-sentence and nothing is lost. No more "I forgot to save my context." - -### Verification Before Completion - -The most impactful rule: Claude cannot claim work is done without running the verification command and reading the output. Eliminates the #1 AI coding failure mode — "should work now" without actually checking. - -### Three-Tier Task Routing +任务完成、每次提交、退出信号时都会自动落盘。半句话关窗也不丢。告别「我忘了保存上下文」。 -Not every task needs Opus. The routing system automatically matches task complexity to model tier: -- **Opus**: Critical logic, security-sensitive, complex reasoning -- **Sonnet**: Daily development, analysis, most coding tasks -- **Haiku**: Simple queries, subagent tasks, quick lookups -- **Codex**: Cross-verification, code review, second opinions -- **Local**: Commit messages, formatting, offline work +### 完成前验证 -### Sunday Rule +核心规则：未运行验证命令并读输出，就不得声称完成。消灭头号失败模式：没检查就说「应该可以了」。 -System optimization happens on Sundays. On other days, if you try to tweak your workflow instead of shipping, Claude will intercept and remind you to focus on output. Configurable to any cadence you prefer. +### 三档（多档）任务路由 -## Customization Guide +不是每件事都需要 Opus。系统按任务复杂度自动匹配模型档位：Opus（关键逻辑/安全/复杂推理）、Sonnet（日常开发）、Haiku（轻量/子任务）、Codex（交叉验证/二阅）、Local（提交信息/格式化/离线）。 -### Adding a new project +### 周日原则 -1. Add to `memory/projects.md` -2. Add memory route in CLAUDE.md's "Sub-project Memory Routes" -3. Create `PROJECT_CONTEXT.md` in the project root +系统优化放在周日。若平日想调工作流而不交付，Claude 会提醒优先产出。周期可改。 -### Adding a new skill +## 定制指南 -Create `skills/your-skill/SKILL.md` with: +### 新项目 -```yaml ---- -name: your-skill -description: What it does -allowed-tools: - - Read - - Write - - Bash ---- +1. 在 `memory/projects.md` 登记 +2. 在 `CLAUDE.md` 的「子项目记忆路由」里加路由 +3. 在仓库根建 `PROJECT_CONTEXT.md` -# Your Skill +### 新 skill -[Instructions for Claude when this skill is invoked] -``` - -### Adding a new agent - -Create `agents/your-agent.md` with: +在 `skills/your-skill/SKILL.md` 中写 frontmatter 与说明（同英文模板）。 -```yaml ---- -name: your-agent -description: What it does -tools: Read, Grep, Glob, Bash ---- - -# Your Agent - -[Agent personality, review dimensions, output format] -``` +### 新 agent -### Adjusting model routing +在 `agents/your-agent.md` 中定义（同英文模板）。 -Edit `rules/behaviors.md` → "Task Routing" section, and `docs/task-routing.md` for detailed tier definitions. +### 调整模型路由 -## Philosophy +编辑 `rules/behaviors.md` 的「任务路由」与 `docs/task-routing.md` 的档位说明。 -This template encodes several principles learned from daily AI-assisted development: +## 设计哲学 -1. **Structure > Prompting**: A well-organized config file beats clever one-off prompts every time. -2. **Memory > Intelligence**: An AI that remembers your past mistakes is more valuable than a smarter AI that starts fresh each session. -3. **Verification > Confidence**: The cost of running `npm test` is always less than the cost of shipping a broken build. -4. **Layered Loading > Flat Config**: Don't dump everything into context. Load rules always, docs on demand, data when needed. -5. **Auto-save > Manual Save**: If it requires the user to remember, it will be forgotten. Make it automatic. +1. **结构 > 单条神 Prompt**：可维护的目录胜过一次性的聪明话术。 +2. **记忆 > 智商**：会记错的模型比每轮重开的天才更有用。 +3. **验证 > 感觉**：跑一遍 `npm test` 比上线坏构建便宜。 +4. **分层加载 > 平铺配置**：常载规则、按需读文档、热数据当需。 +5. **自动保存 > 靠人记得**：人总会忘，自动化才可靠。 -## Requirements +## 环境要求 -- [Claude Code](https://docs.anthropic.com/en/docs/claude-code) CLI (Claude Max or API subscription) -- Optional: Codex CLI for cross-verification -- Optional: Ollama for local model fallback +- [Claude Code](https://docs.anthropic.com/en/docs/claude-code) CLI（Claude Max 或 API 订阅） +- 可选：Codex CLI 做交叉验证 +- 可选：Ollama 作本地回退 -## Prior Art & Credits +## 致谢与来源 -This template draws from: -- [Manus](https://manus.im/) file-based planning approach -- OWASP Top 10 for security review patterns -- Real-world experience from building [x-reader](https://github.com/runesleo/x-reader) (650+ stars) and other open-source projects +- [Manus](https://manus.im/) 的文件化规划思路 +- OWASP Top 10 安全审查模式 +- [x-reader](https://github.com/runesleo/x-reader) 等开源项目实战经验 ## Star History [![Star History Chart](https://api.star-history.com/svg?repos=runesleo/claude-code-workflow&type=Date)](https://star-history.com/#runesleo/claude-code-workflow&Date) -## License +## 许可 -MIT — Use it, fork it, make it yours. +MIT — 随便用、随便改。 -## About the author +## 关于作者 -*Leo ([@runes_leo](https://x.com/runes_leo)) — AI × Crypto independent builder. Trading on [Polymarket](https://polymarket.com/?r=githuball&via=runes-leo&utm_source=github&utm_content=claude-code-workflow), building data and trading systems with Claude Code and Codex.* +*Leo ([@runes_leo](https://x.com/runes_leo)) — AI × Crypto 独立构建者。在 [Polymarket](https://polymarket.com/?r=githuball&via=runes-leo&utm_source=github&utm_content=claude-code-workflow) 交易，用 Claude Code 与 Codex 做数据与交易系统。* -[leolabs.me](https://leolabs.me) — writing · community · open-source tools · indie projects · all platforms. +[leolabs.me](https://leolabs.me) — 写作 · 社区 · 开源小工具 · 独立产品 · 全平台。 -[X Subscription](https://x.com/runes_leo/creator-subscriptions/subscribe) — paid content weekly, or just buy me a coffee 😁 +[X 会员](https://x.com/runes_leo/creator-subscriptions/subscribe) — 每周付费内容，或请杯咖啡 -*Learn in public, Build in public.* +*公开学、公开做（Learn in public, Build in public）。* From 20a4fc86755af1ee62cc11bd1e74fd83f72cab57 Mon Sep 17 00:00:00 2001 From: 7fpb5574ck-maker <369284625@qq.com> Date: Tue, 26 May 2026 15:28:50 +0800 Subject: [PATCH 4/4] chore: consolidate instructions into AGENTS.md with thin delegates Adopt canonical AGENTS.md + thin CLAUDE.md/GEMINI.md entrypoints per instruction-files-ssot.md. Co-authored-by: Cursor --- AGENTS.md | 208 +++++++++++++++++++++++++++++++++++++++++++++++++ CLAUDE.md | 151 +---------------------------------- docs/agents.md | 204 +----------------------------------------------- 3 files changed, 214 insertions(+), 349 deletions(-) create mode 100644 AGENTS.md diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..61f7ce4 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,208 @@ +# Agent Configuration & Multi-Model Collaboration + +> On-demand loading. Contains Agent assignment, Subagent dispatch, multi-model routing rules. + +## Instruction SSOT + +- **`AGENTS.md` (this file, repo root)** is the canonical workspace instruction file. +- `CLAUDE.md` and `docs/agents.md` are thin entrypoints only. + +--- + +## Agent Task Assignment + +### Opus Tier (Critical, highest quality) + +| Agent | Scope | Core Duty | +|-------|-------|-----------| +| **your-critical-agent** | Critical business logic | Validation, quality control | + +### Sonnet Tier (Complex tasks, balance quality/speed) + +| Agent | Scope | Core Duty | +|-------|-------|-----------| +| **pr-reviewer** | Code review | PR quality, architecture consistency | +| **security-reviewer** | Security audit | Vulnerability detection, sensitive info | +| **performance-analyzer** | Performance analysis | Bottleneck identification, optimization | +| **learning-agent** | Experience recording | patterns.md, recall queries | + +### Haiku Tier (Quick tasks) + +| Agent | Scope | Core Duty | +|-------|-------|-----------| +| **build-error-resolver** | Build fixes | TypeScript error quick fixes | + +### Built-in Agents + +| Agent | Model | Use | +|-------|-------|-----| +| general-purpose | sonnet | General multi-step tasks | +| Explore | haiku | Quick codebase exploration | +| Plan | inherit | Architecture design, implementation planning | +| claude-code-guide | haiku | Claude Code usage guide | + +### Coordinator Agent (Main Agent = Claude Opus) + +| Duty | Description | +|------|-------------| +| **Orchestrate** | Dispatch tasks to other Agents/Codex | +| **Decide** | Final judgment on critical matters | +| **Memory** | Maintain hot data layer (today.md) | +| **Align** | Daily status alignment | + +--- + +## Subagent Dispatch Rules + +> **Default parallel, unless there are dependencies** + +**Trigger conditions (dispatch when any met)**: +- >=2 independent tasks +- P0 has multiple pending items +- User says "in parallel" / "simultaneously" +- Complex task can be split into independent modules + +**Memory injection protocol (mandatory when dispatching subagent)**: +``` +You are working on [project-name]. + +## Context Loading (must read first) +1. ~/.claude/memory/today.md — Today's work context +2. /path/to/project/PROJECT_CONTEXT.md — Project status + +## Task +[Specific task description] + +## Completion Requirements +1. Run lint + build yourself, confirm PASS +2. Update PROJECT_CONTEXT.md Session Handoff section +3. Report results +``` + +--- + +## Multi-Model Collaboration + +> Main Agent focuses on orchestration, delegates execution + +### Main Agent Duties (Claude Opus) + +| Do | Don't | +|----|-------| +| Understand requirements, decompose tasks | Write large code blocks | +| Critical decisions | Simple CRUD | +| Verify external output | Document cleanup | +| Maintain memory system | Repetitive tasks | + +### External Model Routing + +| Task Type | Default Executor | Method | +|-----------|-----------------|--------| +| Critical logic | Codex | `codex exec "..."` | +| Frontend / docs | Alternative model | As configured | + +### Sensitive Code (Never outsource) + +- Critical execution logic (orders, state changes, settlements) +- Credential operations (signing, auth, key management) +- Secret/Token handling +- Core business calculations (metrics, risk assessment) + +--- + +## Multi-Model Cross-Verification (Standard Practice) + +> Important analyses/decisions get second-model verification to avoid single-point blind spots + +### Trigger Conditions (Proactive) + +| Scenario | Must Cross-Verify | +|----------|-------------------| +| **Critical business analysis** | Yes | +| **Architecture/system design** | Yes | +| **Strategy decisions** | Yes | +| **Risk assessment** | Yes | +| **Complex bug diagnosis** | Yes | + +### Output Format + +``` +Multi-model cross-verification: +- Claude's view: [xxx] +- Codex/Other view: [xxx] +- Consensus: [xxx] +- Divergence: [xxx] +- Final conclusion: [xxx] +``` + +--- + +## Multi-Model SSOT Collaboration Contract + +> All models use Claude as the hub, unified project state management. + +### Data Layers + +| Layer | Location | Writer | Purpose | +|-------|----------|--------|---------| +| **L0 Rules Layer** | ~/.claude/ | Claude only | Rules, memory, experience | +| **L1 Interface Layer** | PROJECT_CONTEXT.md | All models (restricted) | Project state | +| **L2 Archive Layer** | Knowledge vault | Claude + automation | Persistent knowledge | + +### L1 Interface: PROJECT_CONTEXT.md Structure + +Fixed structure, external models can only write to the Handoff block: + +```markdown +# [Project Name] - Project Context + +## Architecture (Claude maintains) +## Current Focus (Claude maintains) + + +## Session Handoff +- Last: [time] by [model-name] +- Task: [task ID/description] +- Did: [what was done] +- Next: [next steps] +- Blocker: [blockers] + + +## Tech Debt (Claude maintains) +``` + +### External Model Injection Template + +```bash +codex exec " +# Project Contract (must follow) +1. Read PROJECT_CONTEXT.md first for status +2. Only modify code files + content between +3. Never create/modify: ROADMAP.md, FOCUS.md, TODO.md, TASKS.md, STATUS.md +4. Never write to ~/.claude/ or knowledge vault (unless task explicitly requires) +5. After completion, write Handoff: Last: [time] by [model], Task: [description] + +# Task +[specific task description] + +# Verification +[verification commands] +" +``` + +### File Operation Whitelist + +| Model | Can Create | Can Modify | Never Touch | +|-------|-----------|-----------|-------------| +| Claude | Anything (following behaviors.md) | Anything | - | +| External models | Code files | Code + Handoff block | ROADMAP/FOCUS/TODO/TASKS/.claude/vault/ | + +### Violation Detection (Claude executes during review) + +1. `git diff --name-only` — Check for modifications outside whitelist +2. Check PROJECT_CONTEXT.md changes are within `` markers +3. Violation → `git checkout -- [file]` rollback + record in patterns.md + +--- + +*Customize agent assignments and model routing based on your specific projects and needs.* diff --git a/CLAUDE.md b/CLAUDE.md index 4c11648..0d0c790 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -1,150 +1,5 @@ -# Builder Workflow Template — Claude Code Global Memory +# Claude Instructions -> Auto-loaded = rules/ (behaviors.md, skill-triggers.md, memory-flush.md) -> On-demand = docs/ (agents.md, content-safety.md, task-routing.md, behaviors-extended.md, ...) -> Hot data layer → memory/today.md + memory/active-tasks.json +Read **`AGENTS.md`** in the repo root first. It is the canonical workspace instruction file. ---- - -## User Info - -- **Name**: YOUR_NAME | **Project dir**: /path/to/your/projects -- **Identity**: [Your role, e.g. "Full-stack developer" / "AI builder" / "Indie hacker"] -- **X/Twitter**: @your_handle -- **Philosophy**: [Your working philosophy, e.g. "Learn by doing + share publicly"] - - - ---- - -## Delivery Standards - -- **Truth > Speed**: Never claim completion without verification evidence -- **Small Batch**: ≤15 files or ≤400 lines net change per commit -- **No Secrets**: Never commit API keys/tokens -- **Reversible**: Must have rollback path -- **Self-verify**: Run lint/build/test before declaring done, read output to confirm PASS -- **Banned phrases**: "I fixed it, you try" / "Should be fine" / "Probably passes" / "Theoretically correct" / "I think it's fixed" - -Multi-model cross-check (for critical logic): Claude analysis → Codex verification → label `✅ reviewed / ⚠️ unverified` - -### Handoff Checklist (before session-end) - -- [ ] Code committed and passes lint/build/test -- [ ] today.md updated with progress and key decisions -- [ ] MEMORY.md / patterns.md updated with lessons learned -- [ ] Deploy docs updated (if VPS/config changes involved) -- [ ] Remaining issues and v2 improvements noted - ---- - -## Work Preferences - -- **Language**: [Your language] | **Code**: Follow project lint rules | **Commits**: Atomic, one commit = one change -- **Verification**: Claude runs it | **Tests**: Must work offline, use mock/fixtures - ---- - -## Collaboration Preferences - -- Act as advisor, devil's advocate, mirror — proactively point out blind spots, never be a yes-man -- **Auto-execute**: P0/P1 bugs, bug fixes, ≤100 line refactors -- **Auto-intercept**: - * **New project/service** → Ask first: "Can a platform service (Vercel/Supabase/Cloudflare) replace self-hosting?" - * **Tech stack choices** → Prefer low-scaffolding solutions. Target: single feature ≤200 lines, single service ≤3000 lines -- **Require confirmation (Critical decision points — Stop and check in)**: - * Tech stack choices (framework/library/architecture pattern) - * Data model changes (schema/API contract) - * Account/wallet/fund flow changes - * Features outside roadmap - * >100 line refactors - * Trade-offs (performance vs maintainability / speed vs quality) -- **Never self-decide**: Delete projects, production deploys, fund operations -- **Banned**: "Is this OK?" / "Should I pick A or B?" / "Should I continue?" -- **No filler intros**: Don't say "OK let me help" / "Let me take a look" / "Sure!" — go straight to the answer or start working - ---- - -## Experience Recall & Evolution - -**Mandatory triggers (check every conversation turn)**: -- 🔍 **Encountering Bug/Error/Stuck** → First step: `memory_search ""` -- 📝 **Corrected by user** → Immediately: `memory_add` to record lesson -- 🆕 **Starting new task** → Check: patterns.md for related pitfalls - ---- - -- **Recall First**: Encountering Bug/Error → First step: query memory. No recall before debugging = process violation. -- **Self-Evolution**: If executed >8 tools on a complex task, REFLECT: "Which system should capture this learning?" and record it. - ---- - -## SSOT Ownership (Single Source of Truth — modify SSOT first, never create duplicates) - -| Info Type | SSOT File | Do NOT write to | -|-----------|-----------|-----------------| -| Infrastructure/Servers/Cron | `memory/infra.md` | Code comments | -| Project strategic status | Each project's `PROJECT_CONTEXT.md` | today.md, projects.md | -| Cross-project overview | `memory/projects.md` | (summary + pointers only) | -| Technical pitfalls | Each project's `MEMORY.md` | today.md (today = progress only) | -| Daily progress | `memory/today.md` | (temp layer, archived next day) | -| In-flight task registry | `memory/active-tasks.json` | (cross-session task status) | - - - ---- - -## Memory Write Routing - -| Layer | File | What to write | -|-------|------|---------------| -| Auto Memory | Project `MEMORY.md` | Technical pitfalls, API details | -| Pattern library | `patterns.md` | Cross-project reusable patterns | -| Hot data layer | `today.md` | Daily progress, handoff | -| Task registry | `active-tasks.json` | Cross-session in-flight tasks | - -### Sub-project Memory Routes (read before operating on a project) - - - -Routes determine write targets. Unlisted projects share the main MEMORY.md. - ---- - -## On-demand Loading Index - -| Scenario | Load file | -|----------|-----------| -| Project overview | `Read memory/projects.md` | -| Agent/multi-model collaboration | `Read docs/agents.md` | -| AI content safety/quality control | `Read docs/content-safety.md` | -| Task routing details/model costs | `Read docs/task-routing.md` | -| New project/tech stack decisions | `Read docs/scaffolding-checkpoint.md` | -| Behavior reference details | `Read docs/behaviors-reference.md` | -| Extended behaviors (knowledge base, etc.) | `Read docs/behaviors-extended.md` | -| Cross-day goals/todos | `Read memory/goals.md` | -| Pattern library | `Read patterns.md` | - ---- - -*Last updated: YYYY-MM-DD* +On-demand docs: `docs/` (content-safety, task-routing, behaviors-extended, …) diff --git a/docs/agents.md b/docs/agents.md index 3d4cc71..a7543b2 100644 --- a/docs/agents.md +++ b/docs/agents.md @@ -1,203 +1,5 @@ -# Agent Configuration & Multi-Model Collaboration +# Agent Configuration (legacy path) -> On-demand loading. Contains Agent assignment, Subagent dispatch, multi-model routing rules. +Read **`../AGENTS.md`** in the repo root. It is the canonical workspace instruction file. ---- - -## Agent Task Assignment - -### Opus Tier (Critical, highest quality) - -| Agent | Scope | Core Duty | -|-------|-------|-----------| -| **your-critical-agent** | Critical business logic | Validation, quality control | - -### Sonnet Tier (Complex tasks, balance quality/speed) - -| Agent | Scope | Core Duty | -|-------|-------|-----------| -| **pr-reviewer** | Code review | PR quality, architecture consistency | -| **security-reviewer** | Security audit | Vulnerability detection, sensitive info | -| **performance-analyzer** | Performance analysis | Bottleneck identification, optimization | -| **learning-agent** | Experience recording | patterns.md, recall queries | - -### Haiku Tier (Quick tasks) - -| Agent | Scope | Core Duty | -|-------|-------|-----------| -| **build-error-resolver** | Build fixes | TypeScript error quick fixes | - -### Built-in Agents - -| Agent | Model | Use | -|-------|-------|-----| -| general-purpose | sonnet | General multi-step tasks | -| Explore | haiku | Quick codebase exploration | -| Plan | inherit | Architecture design, implementation planning | -| claude-code-guide | haiku | Claude Code usage guide | - -### Coordinator Agent (Main Agent = Claude Opus) - -| Duty | Description | -|------|-------------| -| **Orchestrate** | Dispatch tasks to other Agents/Codex | -| **Decide** | Final judgment on critical matters | -| **Memory** | Maintain hot data layer (today.md) | -| **Align** | Daily status alignment | - ---- - -## Subagent Dispatch Rules - -> **Default parallel, unless there are dependencies** - -**Trigger conditions (dispatch when any met)**: -- >=2 independent tasks -- P0 has multiple pending items -- User says "in parallel" / "simultaneously" -- Complex task can be split into independent modules - -**Memory injection protocol (mandatory when dispatching subagent)**: -``` -You are working on [project-name]. - -## Context Loading (must read first) -1. ~/.claude/memory/today.md — Today's work context -2. /path/to/project/PROJECT_CONTEXT.md — Project status - -## Task -[Specific task description] - -## Completion Requirements -1. Run lint + build yourself, confirm PASS -2. Update PROJECT_CONTEXT.md Session Handoff section -3. Report results -``` - ---- - -## Multi-Model Collaboration - -> Main Agent focuses on orchestration, delegates execution - -### Main Agent Duties (Claude Opus) - -| Do | Don't | -|----|-------| -| Understand requirements, decompose tasks | Write large code blocks | -| Critical decisions | Simple CRUD | -| Verify external output | Document cleanup | -| Maintain memory system | Repetitive tasks | - -### External Model Routing - -| Task Type | Default Executor | Method | -|-----------|-----------------|--------| -| Critical logic | Codex | `codex exec "..."` | -| Frontend / docs | Alternative model | As configured | - -### Sensitive Code (Never outsource) - -- Critical execution logic (orders, state changes, settlements) -- Credential operations (signing, auth, key management) -- Secret/Token handling -- Core business calculations (metrics, risk assessment) - ---- - -## Multi-Model Cross-Verification (Standard Practice) - -> Important analyses/decisions get second-model verification to avoid single-point blind spots - -### Trigger Conditions (Proactive) - -| Scenario | Must Cross-Verify | -|----------|-------------------| -| **Critical business analysis** | Yes | -| **Architecture/system design** | Yes | -| **Strategy decisions** | Yes | -| **Risk assessment** | Yes | -| **Complex bug diagnosis** | Yes | - -### Output Format - -``` -Multi-model cross-verification: -- Claude's view: [xxx] -- Codex/Other view: [xxx] -- Consensus: [xxx] -- Divergence: [xxx] -- Final conclusion: [xxx] -``` - ---- - -## Multi-Model SSOT Collaboration Contract - -> All models use Claude as the hub, unified project state management. - -### Data Layers - -| Layer | Location | Writer | Purpose | -|-------|----------|--------|---------| -| **L0 Rules Layer** | ~/.claude/ | Claude only | Rules, memory, experience | -| **L1 Interface Layer** | PROJECT_CONTEXT.md | All models (restricted) | Project state | -| **L2 Archive Layer** | Knowledge vault | Claude + automation | Persistent knowledge | - -### L1 Interface: PROJECT_CONTEXT.md Structure - -Fixed structure, external models can only write to the Handoff block: - -```markdown -# [Project Name] - Project Context - -## Architecture (Claude maintains) -## Current Focus (Claude maintains) - - -## Session Handoff -- Last: [time] by [model-name] -- Task: [task ID/description] -- Did: [what was done] -- Next: [next steps] -- Blocker: [blockers] - - -## Tech Debt (Claude maintains) -``` - -### External Model Injection Template - -```bash -codex exec " -# Project Contract (must follow) -1. Read PROJECT_CONTEXT.md first for status -2. Only modify code files + content between -3. Never create/modify: ROADMAP.md, FOCUS.md, TODO.md, TASKS.md, STATUS.md -4. Never write to ~/.claude/ or knowledge vault (unless task explicitly requires) -5. After completion, write Handoff: Last: [time] by [model], Task: [description] - -# Task -[specific task description] - -# Verification -[verification commands] -" -``` - -### File Operation Whitelist - -| Model | Can Create | Can Modify | Never Touch | -|-------|-----------|-----------|-------------| -| Claude | Anything (following behaviors.md) | Anything | - | -| External models | Code files | Code + Handoff block | ROADMAP/FOCUS/TODO/TASKS/.claude/vault/ | - -### Violation Detection (Claude executes during review) - -1. `git diff --name-only` — Check for modifications outside whitelist -2. Check PROJECT_CONTEXT.md changes are within `` markers -3. Violation → `git checkout -- [file]` rollback + record in patterns.md - ---- - -*Customize agent assignments and model routing based on your specific projects and needs.* +This file exists for workflows that reference `docs/agents.md` by path.