Back to Details

agent-dev-guardrails

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Agent Dev Guardrails

Agent 开发管控规范

Mental model: The agent is an extremely confident junior dev with amnesia. This skill provides guardrails, progressive context, and automated quality checks.
This skill enforces disciplined development workflows. Essentials are here in SKILL.md; detailed patterns are in 
references/
, loaded only when needed.
心智模型：Agent就像一个极度自信但健忘的初级开发者。本Skill提供管控机制、渐进式上下文以及自动化质量检查。
本Skill用于规范开发工作流。核心内容详见SKILL.md；详细模式存放在
references/
目录下，仅在需要时加载。

Non-Negotiables (Always Apply)

不可妥协的原则（始终遵循）

  1. Plan first, implement second. For non-trivial changes: produce plan, risks, and task checklist before editing.
  2. Work in small slices. Implement 1–2 checklist items at a time; pause for review/testing between slices.
  3. Never leave errors behind. Run checks and fix failures before moving on.
  4. Be explicit about changes. Every response that edits code must include:
    • Files changed (paths)
    • Why the change is correct
    • How it was validated (commands + outcome)
  5. If stuck for 30 minutes, stop. Ask for narrower scope or propose different approach; don't thrash.
  1. 先规划，后实现。 对于非微小变更：在编辑代码前，先产出规划方案、风险评估和任务清单。
  2. 小粒度迭代工作。 每次仅实现1-2项清单任务；在迭代间隙暂停进行评审/测试。
  3. 绝不遗留错误。 运行检查并修复问题后再推进工作。
  4. 明确变更内容。 所有涉及代码编辑的回复必须包含：
    • 变更的文件（路径）
    • 变更的合理性说明
    • 验证方式（命令+结果）
  5. 若卡壳30分钟，立即停止。 请求缩小范围或提出替代方案；不要盲目尝试。

Hook System

钩子系统

Pre-Work Hook (Before Coding)

前置工作钩子（编码前）

Before proposing code changes:
  1. Identify scope — Small fix (no dev-docs) or large task (create dev-docs folder)
  2. State applicable skills — Which domain skills apply (e.g., python-engineering, security)
  3. For non-trivial work:
    • Ask clarifying questions (see references/planning-protocol.md)
    • Produce plan with phases + tasks + risks
    • Wait for plan acceptance before implementation
在提出代码变更前：
  1. 确定范围 —— 微小修复（无需开发文档）或大型任务（创建dev-docs文件夹）
  2. 声明适用Skill —— 适用哪些领域Skill（例如：python-engineering、security）
  3. 对于非微小工作：
    • 提出澄清问题（参见references/planning-protocol.md）
    • 产出包含阶段+任务+风险的规划方案
    • 等待方案获批后再开始实现

Post-Work Hook (After Coding)

后置工作钩子（编码后）

After every code edit:
  1. Run linting — Use 
    ReadLints
    on edited files
  2. Fix failures — Do not leave errors behind
  3. Self-review — Apply specialized roles (see references/specialized-roles.md)
  4. Summarize:
    • Files changed
    • Commands run + outcomes
    • Next slice (if applicable)
每次代码编辑完成后：
  1. 运行代码检查 —— 对编辑的文件使用
    ReadLints
    工具
  2. 修复问题 —— 不得遗留错误
  3. 自审 —— 应用专业化角色（参见references/specialized-roles.md）
  4. 总结：
    • 变更的文件
    • 执行的命令+结果
    • 下一个迭代任务（如有）

When to Read Which Reference

何时查阅对应参考文档

SituationRead
Need to plan or ask clarifying questionsreferences/planning-protocol.md
Complex task (>30 min), need task foldersreferences/dev-docs-system.md
Self-reviewing code after editsreferences/specialized-roles.md
Setting up new project conventionsreferences/project-setup.md
Checking Definition of Donereferences/quality-gates.md
场景查阅文档
需要规划或提出澄清问题references/planning-protocol.md
复杂任务（耗时>30分钟），需要任务文件夹references/dev-docs-system.md
代码编辑后进行自审references/specialized-roles.md
制定新项目规范references/project-setup.md
检查完成标准references/quality-gates.md

Quick Patterns

快速模式

  • Token efficiency: Request only the context you need; reference file paths and symbols instead of pasting large code blocks.
  • Planning: Ask minimum context → produce plan with risks/tasks → wait for acceptance
  • Questions: Ask "What are the tradeoffs? What breaks? What's missing?" not "Is this good?"
  • Slicing: One slice = 1–2 checklist items; each slice ends with validation
  • Review: Apply reviewer role personas (Architecture, Security, Test Engineer)
  • Done: Code compiles, lint passes, edge cases handled, docs updated
  • Token效率：仅请求所需的上下文；引用文件路径和符号，而非粘贴大段代码块。
  • 规划：先询问最少必要上下文 → 产出包含风险/任务的规划方案 → 等待获批
  • 提问：问“有哪些权衡？会破坏什么？遗漏了什么？”而非“这样好吗？”
  • 迭代：一次迭代=1-2项清单任务；每次迭代结束后进行验证
  • 评审：应用评审角色人设（架构师、安全专家、测试工程师）
  • 完成标准：代码可编译、检查通过、边缘场景已处理、文档已更新

Quick Reference / Examples

快速参考/示例

TaskApproach
Start non-trivial workRead references/planning-protocol.md, produce plan, wait for approval
Create task docsRead references/dev-docs-system.md, create 
dev/active/<task-name>/
Self-review codeRead references/specialized-roles.md, apply relevant personas
Set up new projectRun the setup script from the skill's 
scripts/
folder (see references/project-setup.md for path and options)
Check if slice is doneRead references/quality-gates.md, verify all criteria
Pre-work check example:
Scope: Large task (auth feature)
Skills: agent-dev-guardrails + python-engineering
Plan: [3 phases, 8 tasks, 2 risks identified]
Waiting for approval before implementation.
Post-work summary example:
Files changed: src/auth.py, tests/test_auth.py
Validation: ReadLints (0 errors), pytest (12 passed)
Self-review: ✓ Input validation, ✓ No hardcoded secrets, ⚠ Consider rate limiting
Next: Slice 2 (login endpoint)
任务操作方式
启动非微小工作查阅references/planning-protocol.md，产出规划方案，等待获批
创建任务文档查阅references/dev-docs-system.md，创建
dev/active/<task-name>/
目录
代码自审查阅references/specialized-roles.md，应用相关人设
初始化新项目运行Skill的
scripts/
目录下的初始化脚本；详见references/project-setup.md中的路径和选项
检查迭代是否完成查阅references/quality-gates.md，验证所有标准
前置检查示例：
Scope: Large task (auth feature)
Skills: agent-dev-guardrails + python-engineering
Plan: [3 phases, 8 tasks, 2 risks identified]
Waiting for approval before implementation.
后置工作总结示例：
Files changed: src/auth.py, tests/test_auth.py
Validation: ReadLints (0 errors), pytest (12 passed)
Self-review: ✓ Input validation, ✓ No hardcoded secrets, ⚠ Consider rate limiting
Next: Slice 2 (login endpoint)

Workflow

工作流

  1. Starting any change → Check scope, activate skills, follow pre-work hook
  2. Planning complex work → Read references/planning-protocol.md, then references/dev-docs-system.md
  3. After every edit → Follow post-work hook, apply references/specialized-roles.md
  4. Setting up a project → Run the setup script from the skill's 
    scripts/
    folder; see references/project-setup.md
  5. Marking work complete → Verify against references/quality-gates.md
Keep SKILL.md lean; load reference files only when relevant to the task.
  1. 启动任何变更 → 确认范围，激活对应Skill，遵循前置工作钩子
  2. 规划复杂工作 → 先查阅references/planning-protocol.md，再查阅references/dev-docs-system.md
  3. 每次编辑完成后 → 遵循后置工作钩子，应用references/specialized-roles.md
  4. 初始化项目 → 运行Skill的
    scripts/
    目录下的初始化脚本；详见references/project-setup.md
  5. 标记工作完成 → 根据references/quality-gates.md进行验证
保持SKILL.md简洁；仅在与当前任务相关时加载参考文档。