agent-workflow CLAUDE.md

A set of instructions for an AI coding agent working in a software repository. It explains how to track repository status, propose work through RFCs (written design documents), collaborate on changes, and add tests.

In plain words
What is it for?
Use it to guide repository startup, plan new work, preserve other contributors’ changes, and require tests for each feature or bug fix.
Why use it?
It gives the agent a consistent way to understand the project before editing and prevents undocumented changes or fixes without tests.

Instructions file

Install

Getting it into your agent

One page per mod, every tool's command on it. A separate URL per tool would split the same page into five that compete with each other.

agentmods
npx agentmods add instructions/wangbinquan/agent-workflow/claude-md
Clone the repo
git clone --depth 1 https://github.com/wangbinquan/agent-workflow
Per session 10,162 This file is loaded in full into every session.
When invoked 10,162 The same file — it is already loaded in full.
Security scan A 0 findings. Scan, not verified.
Origin original No closer match found in the catalogue.
Token cost

What it costs to keep this loaded

Counted locally with the o200k_base tokenizer, which is exact for GPT models; Claude uses its own tokenizer and its counts differ. Treat this as one consistent yardstick across the catalogue rather than a bill. Prices are per million input tokens.

ModelPer sessionOnce invoked
Fable 5 $0.10162 $0.10162
Opus 5 $0.05081 $0.05081
Sonnet 5 $0.02032 $0.02032
Haiku 4.5 $0.01016 $0.01016

Measured 2d ago against content hash c1e250ad2aec, method: parsed. Prices are Anthropic first-party input rates as of 2026-08-30, from the pricing page.

Security

Grade A, and why

agent-workflow CLAUDE.md scanned grade A with 0 findings against 26 rules in 11 categories — prompt injection, anti-refusal, data exfiltration, privilege escalation, supply chain, agent snooping, system-prompt leakage, SSRF and excessive agency — measured 2d ago.

A static scan of the body, not an audit. Every finding is printed with the line that produced it so you can judge whether it matters here. A mod is markdown that instructs an agent; that is exactly why what it instructs is worth reading.

Nothing flagged

None of the 26 patterns this scan looks for appear in this file: no shell pipes, no recursive deletes, no credential paths, no hidden text, no instruction-override or anti-refusal phrasing, no agent-config snooping. That is not a guarantee, it is the absence of the things that are checkable.

CLAUDE.md · 272 lines

How it starts

The opening of the file, as written. The whole thing — 272 lines — stays where its author put it; the contents beside it link to each section on GitHub.

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Repository status

v1 已发布:M0–M5 的 81 个 issue 全部完工(STATE.md §路线图全局视图:M0 5/5、M1 18/18、M2 16/16、M3 14/14、M4 11/11、M5 12/12),发布产物由 v* tag 触发的 workflow 产出。此后所有产品 / 技术工作一律以 RFC 形式落地design/RFC-NNN-{slug}/),见 §RFC workflow。

Read in this order at session start:

  1. STATE.mdsession-to-session execution log. Always read first; tells you what's done, what's next, current caveats.
  2. design/plan.mdRFC 索引(编号 / 标题 / 状态;新 RFC 在此登记)+ 已完工的 M0–M5 路线图存档。这里已无待认领 issue,新工作从 RFC 开始。
  3. design/RFC-294-backend-layered-target-architecture/ — 后台全局目标架构总纲;新 RFC 的设计必须朝它演进(见 §RFC workflow 第 8 条)。
  4. design/proposal.md — product spec (authoritative).
  5. design/design.md — technical design (authoritative).
  6. proposal/init.md — original Chinese proposal, preserved for history. When it disagrees with design/*.md, design/*.md wins.
  7. docs/dev-gotchas.md — 跨 RFC 沉淀的通用踩坑(提交纪律 / 迁移 / CI / opencode / impl-gate 经验规律 / 前端 / dev-env)。动手前扫一遍,避免重复踩坑;踩到新的通用坑也补进去(RFC-专属细节仍进各 design/RFC-XXX/)。

When a batch of work (RFC tasks, fixes) completes, commit + push and update STATE.md so the next session can pick up seamlessly.

bun install 装依赖。质量 / 测试门禁以 GitHub Actions 为准,本地不再要求跑(2026-08-24 用户明令,详见 §Test-with-every-change 的「运行门槛」):bun run gate:local(完整本地门禁)与 bun run test(backend + shared + frontend)保留为可选的诊断入口——用于复现 CI 报出的红, 不是提交的前置条件。

RFC workflow(新增 / 修改前的强制流程)

任何超出 design/plan.md 已列 issue 范围的新功能、非平凡重构、产品行为变更,必须先走 RFC,再写代码:

  1. 落档:在 design/RFC-NNN-{slug}/ 子目录下创建三件套
    • proposal.md —— 产品视角:背景、目标 / 非目标、用户故事、验收标准
    • design.md —— 技术设计:接口契约、数据流、与现有模块的耦合点、失败模式、测试策略
    • plan.md —— 任务分解:编号子任务(RFC-NNN-T1...)、依赖、PR 拆分建议、验收清单
  2. 编号:递增分配,从 RFC-001 起;在 design/plan.md 的 "RFC 索引" 表里登记新条目(标题 + 状态:Draft / In Progress / Done / Superseded)。
  3. 用户确认:RFC 写完后必须用 ExitPlanMode 或显式询问得到用户批准,才能进入实现阶段。不要边写 RFC 边改代码
  4. STATE.md 同步:RFC 落档同时在 STATE.md 顶部追加一行"进行中 RFC"指向新目录。RFC 完工后把状态改为 Done 并在 STATE.md 已完成 issue 表里加一行(与 P-X-XX 同等级)。
  5. PR:单个 RFC 默认对应单个 PR,commit message 前缀写明 feat(scope): RFC-NNN 标题;如确实需要拆分,在 plan.md 里说明并分别立 PR。
  6. 不走 RFC 的例外:拼写 / 单行 bug 修复、纯重命名、依赖升级、文档增删、测试补充、CI 微调。这些可以直接改 + 提交。
  7. 能力收缩型 RFC 的附加门槛(RFC-224 事故沉淀):凡以安全 / 隔离 / 密封为由关闭或收缩既有能力(含「新路径不再继承旧路径的能力」)的 RFC:
    • proposal.md 必须含**「能力影响清单」**章节:逐项列出被关闭的既有能力与受影响的部署形态,作为 breaking change 呈用户逐项确认——不得以「安全默认」名义静默移除(RFC-224 曾静默切断自定义 provider 网关部署,生产无预警全挂,事后只能以 RFC-251 / RFC-255 逐个受控恢复);
    • 每条禁用 / 拒绝分支必须有测试覆盖(禁用分支与正向功能同等对待,见 docs/dev-gotchas.md 对应教训);
    • 关闭判据必须是可复跑的外部源码引用(file:line),接手复核规则同 docs/dev-gotchas.md §「RFC / design 里对 opencode 行为的既有断言」。
  8. 目标架构对齐(RFC-294 总纲,强制)design/RFC-294-backend-layered-target-architecture/ 定义了后台的全局目标架构——feature-first bounded context + 模块内 domain / application / engine / ports / infrastructure 分层,执行链固定为 TaskEngine → WrapperRuntime → NodeExecutor → ExecutionKernel,跨模块只依赖 exact public/{commands,queries,participants,events,types} 合同,bootstrap 唯一装配。此后每个新 RFC 都必须考虑向该架构做出架构演进
    • design.md 前先读 RFC-294 的 proposal.md §1 摘要裁决 / §3 目标design.md,在设计里写明本次改动落在哪个 bounded context、哪一层,新增代码按目标架构落位
    • 不要再往 routes/ / services/ 横向平铺层加新的跨域耦合、facade 或 cross-context 内部 import;顺手能把触及的存量结构朝目标架构挪一步就挪,并在 design.md 里写清「本 RFC 承担哪一步演进、留下哪些债」;
    • 确有偏离(必须绕过 kernel、必须新增临时 facade 等)时在 design.md逐条列出偏离项与理由并呈用户确认,不得默默沿用旧形状;
    • RFC-294 本身是总纲、零生产改动:各演进波次仍各自立 RFC 单独获批,新 RFC 不因「对齐 294」就自动取得实现许可

Read the full file on GitHub · 272 lines

Changes

What this file has done since we first saw it

Hashed on every crawl. A supply-chain change to an agent config is a question of when, not whether, so the history is kept rather than the latest state alone.

  1. 2d ago First seen · 272 lines · 10,162 tokens per session scan A c1e250ad2aec

Subscribe to this mod's changes

agent-workflow CLAUDE.md is an instructions file published in the GitHub repository wangbinquan/agent-workflow (23 stars, last pushed 2d ago), licensed Apache-2.0. It adds 10,162 tokens to every session, about $0.0508 per session on Opus 5. A static security scan graded it A with 0 findings. No closer match exists in the catalogue, so it is treated as the original; first seen 2026-08-30.

Related

Other instructions, from other repositories

vscode buildNext.instructions.md

Working notes and architecture documentation for the new esbuild-based build system in build/next. Use when making changes to the new build pipeline (transpile/bundle commands, NLS plugin, source-map handling, resource copying, or self-hosting watch tasks).

microsoft/vscode · 6,785 tokens

spec-kit AGENTS.md

AGENTS.md instructions for github/spec-kit, covering agents.md, about spec kit and specify, quickstart — add a new integration in 5 steps, integration architecture and integrationmanifest — file tracking.

github/spec-kit · 7,104 tokens

codex AGENTS.md

AGENTS.md instructions for openai/codex, covering rust/codex-rs, the codex-core crate, code review rules, crate api surface and model visible context.

openai/codex · 5,182 tokens

langchain AGENTS.md

AGENTS.md instructions for langchain-ai/langchain, covering global development guidelines for the langchain monorepo, corridor security analysis, project architecture and context, monorepo structure and development tools & commands.

langchain-ai/langchain · 4,345 tokens

vscode oss-third-party-notices.instructions.md

Instructions for microsoft/vscode, covering vs code oss third-party-notices pipeline, architecture, pipeline flow in ci, applying the notice (cutover) and fallback chain (never fail the build).

microsoft/vscode · 5,001 tokens

next.js AGENTS.md

Instructions for vercel/next.js, covering next.js development guide, codebase structure, monorepo overview, core package: packages/next and other important packages.

vercel/next.js · 7,296 tokens