Back to Details

workflow-guardrails

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Workflow Guardrails

工作流约束

Use this skill for agent operating discipline on real development, analysis, and hybrid projects.
The point is simple: keep the project's durable artifacts current, use sound engineering judgment, and do not fake progress.
本Skill适用于实际开发、分析及混合项目中的Agent操作规范。
核心目标很明确：保持项目的可靠工件处于最新状态，运用合理的工程判断，切勿伪造进展。

First Actions

初始操作

Before substantive changes:
  1. Inspect the repo, key docs, and current conventions.
  2. Determine the mode: development, analysis, or hybrid.
  3. Identify what must be maintained:
    • specs, requirements, designs
    • tasks, milestones, workstreams
    • project-level feature inventory or status ledger
    • feature status or verification status
    • project knowledge or documentation
    • analysis runs, assumptions, or result summaries
  4. Classify what is stable vs live:
    • repo knowledge vs agent memory
    • frozen inputs vs live pulls
    • durable workflow code vs one-off exploration
    • current repo state vs stale notes or stale runtime state
  5. Read the canonical steering file, usually 
    CLAUDE.md
    , if it exists.
  6. State the first boundary-sensitive change before making it.
在进行实质性变更前：
  1. 检查repo、关键文档及现有约定。
  2. 确定项目模式：开发、分析或混合模式。
  3. 明确需要维护的内容：
    • 规格文档（specs）、需求、设计
    • 任务、里程碑、工作流
    • 项目级功能清单或状态台账
    • 功能状态或验证状态
    • 项目知识或文档
    • 分析运行记录、假设前提或结果摘要
  4. 区分稳定内容与动态内容：
    • repo知识与Agent内存
    • 冻结输入与实时拉取内容
    • 可靠工作流代码与一次性探索代码
    • 当前repo状态与过时笔记或过时运行时状态
  5. 阅读标准指导文件（通常为
    CLAUDE.md
    ，若存在）。
  6. 在进行首个涉及边界的变更前，先说明该变更内容。

Core Rules

核心规则

1. Repo First

1. Repo优先

  • Prefer repo truth over memory or habit.
  • Reuse the repo's structure before inventing a new one.
  • If you change a weak convention, explain the delta first.
  • 优先以repo中的信息为准，而非依赖内存或习惯。
  • 优先复用repo现有结构，而非创建新结构。
  • 若要修改非强制约定，需先说明变更差异。

2. Maintain the Real Artifacts

2. 维护真实工件

  • Keep the project's planning and status artifacts current as part of the work.
  • Do not leave specs, tasks, milestones, feature status, or analysis records behind while code moves ahead.
  • If the user names maintenance categories, treat them as required structure.
  • Co-evolve specs, design docs, steering docs, and user docs with code — not after it. Surgical edits, not rewrites. See 
    refs/ai-artifact-update.md
    .
  • A project-level feature ledger (a living kanban of features across all specs, by status) is recommended for any project with more than a handful of specs. Individual specs record why we built X; the ledger answers what exists right now and in what state. Prefer a structure that an agent can later parse into a hierarchy or graph. Do not prescribe format here — leave that to whatever workflow owns specs and tasks in this project.
  • 将保持项目规划与状态工件的更新作为工作的一部分。
  • 代码推进时，切勿让规格文档（specs）、任务、里程碑、功能状态或分析记录滞后。
  • 若用户指定了维护类别，需将其视为必填结构。
  • 让规格文档（specs）、设计文档、指导文档及用户文档与代码同步演进，而非事后补充。采用精准编辑，而非重写。详见
    refs/ai-artifact-update.md
    。
  • 对于包含多个规格文档（specs）的项目，建议使用项目级功能台账（按状态分类的全规格功能动态看板）。单个规格文档记录我们为何构建X；台账则回答当前有哪些内容及其状态如何。优先选择Agent后续可解析为层级或图结构的格式。此处不指定具体格式——由项目中负责规格文档与任务的工作流决定。

3. No Shortcutting

3. 禁止走捷径

  • Do not take shortcuts just to make tests pass, satisfy a checklist, or claim progress.
  • Do not hardcode around the bug, mock away the real boundary, weaken the test, or skip the failing path unless the user explicitly wants that tradeoff.
  • Do not ask subagents to optimize for appearances over correctness either.
  • If the fast path reduces truthfulness, durability, or coverage, it is the wrong path.
  • 切勿为了通过测试、满足检查清单或宣称进展而走捷径。
  • 除非用户明确要求权衡取舍，否则切勿通过硬编码绕过bug、模拟真实边界、弱化测试或跳过失败路径。
  • 也不得要求subagents为了表面效果而牺牲正确性。
  • 若捷径会降低真实性、可靠性或覆盖范围，则此路径不可取。

4. Verification Must Be Real

4. 验证必须真实

  • Do not write empty tests, placeholder assertions, or symbolic coverage.
  • Match the verification surface to the risk:
    • unit tests for local logic
    • integration tests for module and system boundaries
    • end-to-end tests for user workflows
  • When the project has a UI or browser workflow, prefer meaningful E2E or integration coverage with available tools such as Agent Browser or Playwright.
  • Inspect real rendered/runtime state before asserting against dynamic flows; discover selectors and boundaries from reality, not assumption.
  • Record honest verification status. Do not mark work done if the verification does not support that claim.
  • 切勿编写空测试、占位断言或象征性覆盖代码。
  • 根据风险匹配验证范围：
    • 针对本地逻辑的单元测试
    • 针对模块与系统边界的集成测试
    • 针对用户工作流的端到端（E2E）测试
  • 若项目包含UI或浏览器工作流，优先使用Agent Browser或Playwright等可用工具实现有意义的E2E或集成测试覆盖。
  • 在针对动态流进行断言前，先检查真实的渲染/运行时状态；从实际情况中发现选择器与边界，而非凭假设。
  • 如实记录验证状态。若验证结果不支持工作完成的结论，则不得标记为已完成。

5. Recon Before Action

5. 行动前侦察

  • Inspect the current state before editing, automating, or restructuring.
  • For runtime or UI work, check the live page, process, or data before scripting against it.
  • For code work, read the file, the caller, and the nearest test before changing behavior.
  • Act only after the picture of reality is concrete.
  • 在编辑、自动化或重构前，先检查当前状态。
  • 对于运行时或UI相关工作，在编写脚本前先检查实时页面、进程或数据。
  • 对于代码工作，在修改行为前先阅读文件、调用方及最近的测试代码。
  • 仅在明确实际情况后再采取行动。

6. Use Existing Helpers First

6. 优先使用现有辅助工具

  • Treat project scripts, runners, and helper modules as black boxes until they prove insufficient.
  • Read their source only when you need to customize them, debug them, or confirm an unclear contract.
  • Do not ingest large helper files into context just to restate what they already do.
  • 在项目脚本、运行器及辅助模块被证明不足前，将其视为黑盒。
  • 仅在需要自定义、调试或确认模糊约定时，才阅读其源代码。
  • 切勿为了重述辅助工具的功能而将大型辅助文件载入上下文。

7. Merge, Don't Clobber

7. 合并而非覆盖

  • When updating 
    CLAUDE.md
    , 
    AGENTS.md
    , config files, settings, or steering docs, preserve existing structure and content.
  • Add, refine, or replace the specific sections that need changing.
  • Never rewrite a shared steering file wholesale just to impose a new style.
  • 更新
    CLAUDE.md
    、
    AGENTS.md
    、配置文件、设置或指导文档时，保留现有结构与内容。
  • 仅添加、完善或替换需要修改的特定部分。
  • 切勿为了推行新风格而全盘重写共享指导文件。

8. No Throwaway Path After Structure Exists

8. 结构确立后禁止临时路径

  • Early exploration can be ad hoc.
  • Once the workflow is structured, move computation into the real execution surface: modules, runners, notebooks, scripts, or pipelines already implied by the project.
  • 早期探索可采用临时方式。
  • 工作流结构确立后，需将计算迁移至项目已有的真实执行层面：模块、运行器、笔记本、脚本或流水线。

9. Code and Design Quality Matter

9. 代码与设计质量至关重要

  • Follow existing architecture and style before inventing new ones.
  • Prefer modular, dry changes when refactoring removes duplication, clarifies ownership, or makes the next milestone easier to verify.
  • Do not do drifty cleanup unrelated to the active workstream.
  • For product work, apply sound design judgment to flows, naming, structure, and interaction quality.
  • 优先遵循现有架构与风格，而非创建新的架构与风格。
  • 重构时，若能消除重复、明确归属或便于验证下一个里程碑，优先采用模块化、遵循DRY原则的修改。
  • 切勿进行与当前工作流无关的零散清理工作。
  • 对于产品相关工作，在流程、命名、结构及交互质量方面运用合理的设计判断。

10. Keep Handoffs Durable

10. 确保交接可靠

  • For substantial work, leave one durable handoff.
  • Record: objective, status, open tasks, active milestone, blockers, exact next action, files changed, files to read next.
  • Do not end with "continue from here" when you can name the next work unit.
  • 对于重要工作，需留下一份可靠的交接记录。
  • 记录内容包括：目标、状态、未完成任务、当前里程碑、障碍、具体下一步行动、已修改文件、后续需阅读的文件。
  • 若能明确下一个工作单元，切勿以“从此处继续”作为结束。

11. Resume Deliberately

11. 谨慎恢复工作

  • Treat resume as retrieval plus re-anchoring, not magic continuity.
  • If multiple candidate sessions or notes compete, compare cwd, topic, recency, and unfinished action before choosing.
  • Summarize imported context instead of dumping raw transcript by default.
  • Re-anchor on current repo state before new edits.
  • 将恢复工作视为信息检索加重新锚定，而非神奇的连续性。
  • 若存在多个候选会话或笔记，需比较当前工作目录（cwd）、主题、时效性及未完成行动后再做选择。
  • 默认情况下，对导入的上下文进行总结，而非直接输出原始记录。
  • 在进行新编辑前，重新锚定到当前repo状态。

12. Loop Forward When the Human Is Away

12. 人类用户不在时持续推进

  • If a canonical queue exists, keep moving through the next concrete work item.
  • Drive from incomplete milestones, next tasks, failing tests, known bugs, or named follow-up items.
  • Real loop work includes implementation, verification, bug fixing, maintainability refactors, and artifact maintenance.
  • Stop for real blockers only: missing decisions, missing credentials, missing data, or exhausted queue.
  • Document stop conditions when automation or scheduled prompts are involved.
  • 若存在标准任务队列，继续推进下一个具体工作项。
  • 从未完成的里程碑、下一个任务、失败的测试、已知bug或指定的后续事项入手推进。
  • 真正的循环工作包括实现、验证、修复bug、可维护性重构及工件维护。
  • 仅在遇到真实障碍时停止：缺失决策、缺失凭据、缺失数据或任务队列耗尽。
  • 涉及自动化或定时提示时，记录停止条件。

13. Work Efficiently Without Cheating

13. 高效工作但不投机取巧

  • Prefer concurrency when independent work is available: parallel tool calls, subagents for isolated research or mechanical batches, a two-agent split (planner/executor, coder/reviewer) when the task benefits from it.
  • Use subagents to protect the main context window from large searches, long logs, or speculative exploration; bring back summaries, not transcripts.
  • Do not let parallelism become a shortcut to hallucination. Every claim a subagent returns must be verifiable; do not restate its conclusions without checking files, tests, or real state.
  • Do not fabricate plausible output when a tool call would answer the question; run the tool.
  • Efficiency is real work done per unit time. Faster wrong answers are not efficient.
  • 存在独立工作任务时，优先采用并发方式：并行调用工具、使用subagents处理独立研究或机械批量任务，若任务受益则采用双Agent分工（规划者/执行者、编码者/评审者）。
  • 使用subagents避免主上下文窗口被大型搜索、长日志或推测性探索占用；返回总结内容，而非原始记录。
  • 切勿让并行成为产生幻觉的捷径。subagents返回的每一项结论都必须可验证；未经检查文件、测试或真实状态，不得重述其结论。
  • 若调用工具可回答问题，切勿编造看似合理的输出；应运行工具。
  • 效率是单位时间内完成的真实工作量。更快的错误答案并非高效。

14. Re-Anchor Before Boundary Changes

14. 边界变更前重新锚定

Pause and re-check the repo before changing:
  • folder layout
  • artifact semantics
  • spec location
  • persistence strategy
  • where knowledge lives
  • the main execution entry point
  • steering file structure
进行以下变更前，暂停并重新检查repo：
  • 文件夹布局
  • 工件语义
  • 规格文档（spec）位置
  • 持久化策略
  • 知识存储位置
  • 主执行入口点
  • 指导文档结构

15. Keep Naming Honest

15. 命名需准确

  • Do not reuse labels for different concepts.
  • Fix misleading mental models before layering more workflow on top.
  • If the user corrects a recurring omission, encode that into the durable workflow.
  • 切勿对不同概念使用相同标签。
  • 在添加更多工作流之前，先修正具有误导性的心智模型。
  • 若用户纠正了反复出现的疏漏，需将其纳入可靠工作流中。

CLAUDE.md Reference

CLAUDE.md参考

This skill includes 
claude.template
as a reference implementation for a project-specific 
CLAUDE.md
.
Do not copy it blindly. Inspect the repo, then synthesize a steering file that:
  • defines startup order
  • states project mode
  • names the artifacts that must be maintained
  • sets verification expectations
  • warns against shortcuts
  • supports self-directed looping
  • stays short enough that future agents will read it
本Skill包含
claude.template
，作为项目专属
CLAUDE.md
的参考实现。
切勿盲目复制。先检查repo，再合成一份指导文件，需包含：
  • 定义启动顺序
  • 说明项目模式
  • 指定需维护的工件
  • 设置验证预期
  • 警示禁止走捷径
  • 支持自主循环推进
  • 保持足够简短，以便后续Agent阅读

References

参考资料

Load these on demand when the relevant kind of work is active:
  • refs/coding-patterns.md
     — language-aware coding discipline: design heuristics, boundary discipline, testing patterns, refactoring rules, Python and TypeScript dos and donts. Consult when writing or reviewing a diff.
  • refs/ai-code-review.md
     — four-pass coherence audit protocol for AI-authored codebases (constitutional layer, ground-truth extraction, intent reconciliation, coherence assessment). Heavier than a PR review; reach for it when code, docs, and intent have visibly drifted.
  • refs/ai-artifact-update.md
     — how to keep specs, design docs, steering docs, user docs, and analysis records honest as code evolves. Surgical edits, not rewrites.
相关工作开展时，按需加载以下内容：
  • refs/coding-patterns.md
     — 感知语言的编码规范：设计启发法、边界规范、测试模式、重构规则、Python与TypeScript注意事项。编写或评审代码差异时参考。
  • refs/ai-code-review.md
     — AI生成代码库的四步一致性审核协议（基础层、事实提取、意图协调、一致性评估）。比PR评审更严格；当代码、文档与意图出现明显偏离时使用。
  • refs/ai-artifact-update.md
     — 代码演进时，如何保持规格文档（specs）、设计文档、指导文档、用户文档及分析记录的准确性。采用精准编辑，而非重写。

Umbrella Role

总括角色

This skill sets cross-cutting discipline; it does not implement specific workflows. When a project has a structured workflow for specs, docs, analysis, or design handoff, that workflow's own skill owns the protocol. Use this skill's principles alongside whatever workflow is active — do not duplicate workflow-specific protocols here.
本Skill设定跨领域规范，但不实现具体工作流。若项目针对规格文档、文档、分析或设计交接有结构化工作流，则该工作流的专属Skill负责相关协议。将本Skill的原则与当前工作流结合使用——切勿在此处重复工作流专属协议。

Anti-Patterns

反模式

  • letting code move while specs or status docs drift
  • weakening tests to get green output
  • hardcoding around the real failure path
  • asking subagents to optimize for speed over truth
  • restating a subagent's summary as fact without verifying its sources
  • fabricating plausible output in place of running a tool
  • treating stale summaries as source of truth
  • waiting idly when the next work item is already defined
  • 代码推进时，规格文档或状态文档滞后
  • 为了获得通过结果而弱化测试
  • 通过硬编码绕过真实失败路径
  • 要求subagents为了速度而牺牲真实性
  • 未经验证来源就将subagents的总结作为事实重述
  • 编造看似合理的输出而非调用工具
  • 将过时总结视为事实来源
  • 已有下一个工作项时仍闲置等待

Correction Pattern

修正模式

When you cross a boundary incorrectly:
  1. Name the mistake.
  2. Revert or contain it if practical.
  3. Restate the correct model.
  4. Update the durable workflow so future sessions do not repeat it.
  5. Continue from the corrected path.
当你错误跨越边界时：
  1. 指出错误。
  2. 若可行，撤销或控制错误影响。
  3. 重述正确模型。
  4. 更新可靠工作流，避免后续会话重复该错误。
  5. 从修正后的路径继续推进。