auto-dev

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Auto-Dev Skill

Auto-Dev Skill

WHEN TO USE: Task requires building, modifying, or fixing software, tools, or systems and requirements are clear (confidence: MEDIUM or HIGH).
适用场景: 任务要求构建、修改或修复软件、工具或系统,且需求明确(置信度:中等或高)。

Development Philosophy

开发理念

Think like an engineer, not a code generator. Quality comes from understanding, not speed.
Define done — Before touching code, articulate what success looks like. What should work? What must not break? What is out of scope? This is your anchor for every decision that follows. Without it, scope drifts silently.
Understand before you change — Read the code you're about to modify. Read its callers, its callees, its tests. Map the blast radius. Your change quality is bounded by your understanding quality — when things go wrong, it's almost always because you understood too little, not because you coded too little.
Present, then act — After understanding, describe what you found and what you plan to do before doing it. The most productive sessions are those where design is discussed before code is written. The worst sessions are those where the agent reads files and immediately starts editing.
One correct change — Re-read the file before each edit. Make one comprehensive change, not ten incremental patches. If you find yourself editing the same file a third time, stop — you don't understand it well enough yet.
Every result is evidence — A test failure is not "retry with a tweak." Read the assertion. What does it actually say? A passing test suite is not "done" — does it exercise the behavior you changed? An error message is not "try something else" — what specifically went wrong?
Check against ①, stop — When the success criteria from ① are met, deliver. Don't improve what wasn't asked for. Don't refactor adjacent code. Don't absorb new scope mid-task. If a new request arrives, explicitly decide: defer, replace, or acknowledge the expansion.
像工程师一样思考,而不是代码生成器。质量源于理解,而非速度。
定义完成标准 —— 动手写代码之前,先明确成功的标准是什么。哪些功能要正常运行?哪些功能绝对不能出问题?哪些内容不在本次范围内?这是你后续所有决策的锚点。没有这个标准,范围会在无形中不断蔓延。
变更前先充分理解 —— 通读你要修改的代码,阅读它的调用方、被调用方、相关测试。评估变更的影响范围。你的变更质量上限由你的理解程度决定——出问题的时候,几乎都是因为你理解得不够,而不是写代码写得不够。
先方案沟通,再动手执行 —— 理解清楚现有逻辑后,先说明你梳理的现状和计划执行的方案,再开始动手。最高效的开发会话都是写代码前先讨论设计,最差的会话都是Agent读完文件就立刻开始编辑。
一次做对变更 —— 每次编辑前重新通读文件,做一次全面的修改,而不是打十个零散的补丁。如果你发现自己第三次编辑同一个文件,立刻停下——说明你对它的理解还不够充分。
所有结果都是证据 —— 测试失败不是「微调一下再重试」,要读断言信息,它实际表达的是什么?测试套件全过也不等于「做完了」,它有没有覆盖你修改的行为?报错信息不是「试试别的方法」,要搞清楚具体是什么地方出了问题。
对照①的标准,完成即停止 —— 当①中定义的成功标准都满足时,就交付成果。不要优化需求没要求的内容,不要重构相邻的代码,不要在任务中途承接新的范围。如果有新需求进来,明确做出决策:延后处理、替换当前任务,或者确认范围扩张。

Task Classification

任务分类

SignalParadigm
New project/system, no existing codebase
dev/architecture-first
Defect, regression, incorrect behavior
bugfix/hypothesis-driven
Single function/component, fits existing architecture unchanged
addition/lightweight
Everything else (feature addition, behavior extension)
enhancement/delta-design
When in doubt
enhancement/delta-design
. If a paradigm's quality gates reveal mismatch → escalate.
信号范式
新项目/新系统,无现有代码库
dev/architecture-first
缺陷、回退、行为不符合预期
bugfix/hypothesis-driven
单一函数/组件,完全适配现有架构无需修改
addition/lightweight
其他所有情况(新增功能、行为扩展)
enhancement/delta-design
不确定时 → 选择
enhancement/delta-design
。如果某个范式的质量门显示不匹配,就升级处理。

Paradigm System

范式系统

Development workflows are composed from phases (reusable steps) organized into paradigms (ordered sequences).
开发工作流由Phase(阶段,可复用步骤)组成,这些阶段被组织成Paradigm(范式,有序序列)

Phases

阶段

Each phase is a self-contained markdown file in
phases/
with defined inputs, outputs, and quality gates:
PhasePurpose
validate-requirementsEnsure requirements are clear and actionable
test-planDefine boundaries, forbidden zones, and Must Have checkpoints (TPDD)
architectureDesign system structure with complexity analysis
impact-analysisMap existing structure and design the delta for enhancements
diagnoseHypothesis-driven bug diagnosis to find root cause
extract-contractsExtract interface stubs for parallel sessions
implementBuild against architecture, impact doc, or diagnosis doc
code-reviewReview for structural and design quality
verifyVerify against TestPlan checkpoints — capability, integration, and E2E (environment-aware)
provision-environmentAuto-provision Docker environment for real E2E verification (optional)
deliverReport completion with structured output
每个阶段都是
phases/
目录下独立的markdown文件,有定义明确的输入、输出和质量门:
阶段用途
validate-requirements确保需求清晰可执行
test-plan定义边界、禁止修改范围和必达检查点(TPDD)
architecture设计系统结构并做复杂度分析
impact-analysis梳理现有结构,设计增强功能的变更范围
diagnose假设驱动的缺陷诊断,定位根因
extract-contracts提取接口存根,支持并行开发会话
implement基于架构设计、影响分析文档或诊断文档进行开发
code-review评审结构和设计质量
verify对照测试计划的检查点做验证——功能验证、集成验证和E2E验证(感知环境)
provision-environment自动 provision Docker 环境用于真实E2E验证(可选)
deliver输出结构化内容报告任务完成

Paradigms

范式

Task TypeParadigmDescription
Greenfielddev/architecture-firstFull TestPlan + architecture design before implementation
Enhancementenhancement/delta-designImpact-analysis-driven workflow for existing codebases
Bugfixbugfix/hypothesis-drivenHypothesis-driven diagnosis, minimal surgical fix
Additionaddition/lightweightLightweight workflow for single well-scoped additions
任务类型范式描述
全新项目dev/architecture-first开发前先完成完整的测试计划和架构设计
功能增强enhancement/delta-design基于影响分析的现有代码库工作流
缺陷修复bugfix/hypothesis-driven假设驱动的诊断,最小侵入式精准修复
功能新增addition/lightweight适用于单个边界清晰的新增需求的轻量工作流

Shared Protocols

共享协议

ProtocolPurpose
parallel-executionCross-cutting execution strategy for parallel submodule implementation (M/L/XL, >=2 independent modules)
协议用途
parallel-execution适用于并行子模块开发的跨领域执行策略(中/大/超大任务,>=2个独立模块)

How to Use

使用方法

  1. Classify the task — use the Task Classification table above
  2. Select the paradigm — the table maps signals to paradigms
  3. Announce your phase sequence — state which phases you will follow before starting. This announcement is your commitment. In the best-performing sessions, this step alone ensured full adherence.
  4. Follow the phase sequence — read each phase file when you enter that phase, not all upfront
  5. Check for parallel execution — if M/L/XL with >=2 independent modules, see parallel-execution
  6. Respect quality gates — each phase defines what must be true before proceeding
  7. Escalate if needed — if quality gates reveal the paradigm doesn't fit, switch to the appropriate one
  8. Re-evaluate complexity — if during implementation you discover 3+ files need changes or >50 lines of modification beyond initial estimate, stop and re-classify
  1. 任务分类 —— 使用上方的任务分类表判断任务类型
  2. 选择范式 —— 表格中已经映射了信号对应的范式
  3. 公示阶段序列 —— 开始前说明你要遵循的阶段,这个公示是你的执行承诺。在表现最好的开发会话中,仅这一步就保证了流程的完全落地。
  4. 遵循阶段序列执行 —— 进入对应阶段时再阅读该阶段的文件,不要提前通读所有内容
  5. 检查是否需要并行执行 —— 如果是中/大/超大任务,且包含>=2个独立模块,参考parallel-execution
  6. 遵守质量门要求 —— 每个阶段都定义了进入下一阶段前必须满足的条件
  7. 必要时升级处理 —— 如果质量门显示当前范式不匹配,切换到合适的范式
  8. 重新评估复杂度 —— 如果开发过程中发现需要修改3个以上文件,或者修改行数超出初始预估50行以上,停下并重新分类任务

Key Constraints

核心约束

  • Don't start coding from LOW confidence requirements
  • Don't skip design thinking — use the appropriate paradigm for the task type
  • Don't mark complete without runnable, verifiable result
  • Don't run destructive commands without asking
  • 不要基于低置信度的需求开始编码
  • 不要跳过设计思考——为任务类型选择合适的范式
  • 没有可运行、可验证的成果不要标记完成
  • 不要在未询问的情况下执行破坏性命令

What Coding Agents Get Wrong

编码Agent常犯错误

Coding agents have predictable failure patterns that undermine autonomous delivery. Naming them helps resist them.
  • Code-first impulse. The default is to start editing immediately. Even when told to follow a process, agents revert to inline coding within minutes. In sessions where the agent announced its phase sequence upfront, outcomes were measurably better. The phases exist to prevent this — skipping them is the single largest source of rework.
  • Patch-and-pray. Instead of reading a file completely and making one correct change, agents make small local edits, test, find a secondary issue, patch that, test again — each fix shifting the bug elsewhere. A file edited 10+ times usually needed 1-2 edits with proper upfront understanding. Before editing, re-read the file — your in-context memory drifts from reality after each change.
  • First-diagnosis anchoring. The agent commits to its first interpretation and filters subsequent evidence to confirm it. When evidence contradicts, it patches within the same mental frame rather than re-examining the frame itself. Wrong architectural layer, wrong hook point, wrong root cause — all from committing too early. State your assumptions explicitly and check each one.
  • Test theater. Two forms: (a) running the same failing test repeatedly with speculative micro-fixes instead of deeply reading the assertion failure; (b) tests that pass but don't verify actual user-facing behavior. Unit tests passing while the deployed feature returns 500s. "Tests pass" ≠ "it works."
  • Complexity ratchet. When a simple approach would work, agents reach for a sophisticated one — more abstraction, more indirection, more configuration. Timestamp comparison becomes git-stash SHA diffing. The result is harder to debug and often doesn't work on the first attempt. Ask: what is the simplest thing that solves this correctly?
  • Scope absorption. Agents never say "that's a separate task." Every request gets folded into the current work. A bugfix becomes a bugfix + refactor + new feature + test rewrite. One task at a time — finish before starting the next.
  • Environment amnesia. Agents run commands without verifying environment assumptions: wrong working directory, missing dependencies, wrong paths, wrong API endpoints. They also guess instead of reading — when a config file would give the answer immediately, agents probe blindly. Read configs and docs before running commands in unfamiliar environments.
  • Reasoning over reading. After reading a file once, agents prefer to reason from stale in-context memory rather than re-reading the current state. Files change between edits. Error messages contain the answer if you actually read them. Re-read, don't theorize.
编码Agent存在可预测的错误模式,会影响自主交付的质量。明确这些问题可以避免踩坑。
  • 优先写代码的冲动。 默认行为是立刻开始编辑,即使被要求遵循流程,Agent也会在几分钟内退回直接写代码的模式。如果Agent提前公示了阶段序列,结果会明显更好。阶段的存在就是为了避免这个问题——跳过阶段是返工的最大单一来源。
  • 碰运气式补丁修复。 Agent不会完整通读文件做一次正确的修改,而是做小的局部修改、测试、发现第二个问题、打补丁、再测试——每次修复都把问题转移到别的地方。一个被编辑10次以上的文件,通常只要提前充分理解,做1-2次修改就能解决问题。编辑前重新通读文件——每次变更后你上下文里的记忆已经和实际内容有偏差了。
  • 初始诊断锚定效应。 Agent会执着于第一个得出的结论,后续的证据都会被过滤用来验证这个结论。当出现矛盾的证据时,它会在现有思维框架内打补丁,而不是重新审视框架本身。错误的架构层、错误的钩子点、错误的根因——都源于过早下结论。要明确说明你的假设,逐一验证。
  • 测试表演。 有两种形式:(a)反复运行同一个失败的测试,做猜测式的微小修改,而不是深入阅读断言报错信息;(b)测试通过但没有验证实际用户侧的行为,单元测试全过但部署后的功能返回500。「测试通过」≠「功能正常」。
  • 复杂度棘轮效应。 明明简单的方案就能解决问题,Agent却会选择复杂的方案——更多抽象、更多间接层、更多配置。时间戳比较变成了git-stash SHA比对,结果更难调试,而且通常第一次跑不起来。要问自己:能正确解决问题的最简单方案是什么?
  • 范围主动承接。 Agent永远不会说「这是另一个任务」,所有需求都会被纳入当前工作。一个缺陷修复最后变成了缺陷修复+重构+新功能+测试重写。一次只做一个任务——完成当前任务再开始下一个。
  • 环境遗忘症。 Agent执行命令前不会验证环境假设:工作目录错误、依赖缺失、路径错误、API端点错误。它们也会猜测而不是阅读——明明配置文件就能立刻给出答案,Agent却会盲目试探。在不熟悉的环境执行命令前,先读配置和文档。
  • 靠推理不靠重读。 读过一次文件后,Agent更愿意基于过时的上下文记忆推理,而不是重读当前的文件状态。文件在两次编辑之间会发生变化,只要你认真读,报错信息里就有答案。重读,不要空想。

Project Experience

项目经验

Working knowledge accumulated during development, stored per project in
references/project-patterns/
.
Existing project experience:
ls references/project-patterns/ 2>/dev/null | sed 's/\.md$//' || echo "none yet"
When starting work on a project, check if experience exists and load it. Experience entries are dated — treat as hints, not guarantees. If following a pattern leads to failures, fall back to first-principles and update the entry.
After completing a task, if you discovered reusable project knowledge (codebase conventions, build/test patterns, architecture decisions, recurring pitfalls), write or update the project experience file. Only write verified facts.
File format:
markdown
---
project: project-name
aliases: [alt-name-1, alt-name-2]
updated: YYYY-MM-DD
---
开发过程中积累的可复用知识,按项目存储在
references/project-patterns/
目录下。
现有项目经验:
ls references/project-patterns/ 2>/dev/null | sed 's/\.md$//' || echo "none yet"
开始处理某个项目的任务时,先检查是否存在已有经验并加载。经验条目有日期标记,仅作为参考,不是保证。如果遵循某个模式导致失败,回归第一性原理并更新对应条目。
完成任务后,如果你发现了可复用的项目知识(代码库规范、构建/测试模式、架构决策、常见陷阱),编写或更新项目经验文件,仅写入已验证的事实。
文件格式:
markdown
---
project: project-name
aliases: [alt-name-1, alt-name-2]
updated: YYYY-MM-DD
---

Codebase Conventions

代码库规范

Naming, directory structure, error handling, import patterns
命名、目录结构、错误处理、导入模式

Build & Test

构建与测试

Commands, frameworks, runners, what works
命令、框架、运行器、可用方案

Architecture Decisions

架构决策

Key design choices and rationale
核心设计选择和背后的原因

Known Pitfalls

已知陷阱

What breaks and why — environment quirks, platform issues, recurring review findings

Experience content is dated. Treat as "likely valid hints" not "guaranteed facts."
什么会出问题、原因是什么——环境特性、平台问题、反复出现的评审发现

经验内容有时间标记,将其视为「大概率有效的参考」,而非「绝对正确的事实」。

Design Principles

设计原则

Principles in
principles/
are loaded selectively — not all at once. Load when the current phase requires quality evaluation:
WhenLoad
architecture phaseAll principles
impact-analysis phasecohesion-separation, information-hiding, abstraction-layers
code-review phasePrinciples relevant to the changes made
implement phasenaming-obviousness, error-handling
diagnose phaseerror-handling
Other phasesNone required
Principles: module-depth, information-hiding, abstraction-layers, cohesion-separation, error-handling, naming-obviousness, documentation, strategic-design
principles/
目录下的原则是按需加载的,不需要一次性全部加载。当前阶段需要做质量评估时再加载:
时机加载内容
架构阶段所有原则
影响分析阶段cohesion-separation, information-hiding, abstraction-layers
代码评审阶段和本次变更相关的原则
开发阶段naming-obviousness, error-handling
诊断阶段error-handling
其他阶段无需加载
原则列表:module-depth, information-hiding, abstraction-layers, cohesion-separation, error-handling, naming-obviousness, documentation, strategic-design

References

参考资源

ResourceWhen to Load
phases/{phase}.md
When entering that phase (not all upfront)
paradigms/{type}/{name}.md
After task classification
principles/{name}.md
During architecture or code-review (see table above)
paradigms/parallel-execution.md
M/L/XL tasks with >=2 independent modules
references/project-patterns/{project}.md
When starting work on a known project
config/defaults.json
When output path configuration is needed
examples/
When you need format reference for design docs or code reviews
资源加载时机
phases/{phase}.md
进入对应阶段时(不要提前通读所有)
paradigms/{type}/{name}.md
任务分类完成后
principles/{name}.md
架构或代码评审阶段(参考上方表格)
paradigms/parallel-execution.md
包含>=2个独立模块的中/大/超大任务
references/project-patterns/{project}.md
开始处理已知项目的任务时
config/defaults.json
需要配置输出路径时
examples/
需要设计文档或代码评审的格式参考时