实用提示：别再盯着你的编程助手看了——打造一个值得信赖的系统

可将此内容视为《别再盯着你的编码助手：构建值得信赖的系统》一文中理念的面向操作员的优化版本：清晰的阶段划分、有序的代码模块，以及能在交接时保留的恢复说明。在“概览”阶段，若能将其视为可量化的基准，效果最佳——在扩大范围之前，先记录一份理想的执行日志、一个故障案例以及对应的回滚说明。相比庞大的脚本，应优先使用小型且可测试的单元。当某一步骤出错时，故障原因应能明确指向某个特定职责，而非复杂的流程链。

问题所在：你可能仍只完成了半数工作

针对当前所处的阶段，应在修改代码之前明确输入参数、该步骤的负责人以及结束标准。操作人员应能够从已知的检查点重新运行该步骤，而无需猜测隐藏状态。 将此阶段视为输入与经过验证的输出之间的契约。为相关成果命名，定义成功判定标准，杜绝默许的半完成状态。 对于涉及资金支出或修改生产数据的操作，必须经过人工审批。编译时的逻辑连接并不等同于业务上的完整性。

You: Fix the login bug.
Agent: Done.
You: opens browser
You: It still doesn't work.
Agent: Ah. I found the problem.
You: No, that's not it.
Agent: You're right. I found the REAL problem.
You: sends screenshot
Agent: Ah...

1. 为智能体提供一条用于标记“完成”的指令

在进入“1. 分配代理”阶段时，应在修改代码之前明确输入参数、该步骤的负责人以及结束标准。操作人员应能够从已知的检查点重新运行该步骤，而无需猜测隐藏状态。除了功能结果外，还需记录执行时间以及令牌或查询成本。提前了解成本情况，可避免在从演示环境切换到共享环境时出现意外费用。对于会消耗资金或修改生产数据的操作，必须经过人工审批。编译时的配置并不等同于业务功能的完整性。

scripts/verify.sh

#!/usr/bin/env bash
set -euo pipefail

echo "== Python lint =="
uv run ruff check backend

echo "== Python types =="
uv run mypy backend

echo "== Python tests =="
uv run pytest -q

echo "== Frontend lint =="
npm --prefix frontend run lint

echo "== Frontend tests =="
npm --prefix frontend test -- --run

echo "Verification passed."

#!/usr/bin/env bash
set -euo pipefail

echo "== Python lint =="
python -m ruff check backend

echo "== Python types =="
python -m mypy backend

echo "== Python tests =="
python -m pytest -q

echo "== Frontend lint =="
npm --prefix frontend run lint

echo "== Frontend tests =="
npm --prefix frontend test -- --run

echo "Verification passed."

chmod +x scripts/verify.sh

verify:
        ./scripts/verify.sh

make verify

inspect
↓
change code
↓
verify
↓


failure
↓
inspect
↓
change code
↓
verify

2. 针对漏洞，要求在修复前提供证据

在2 For bugs需求阶段，修改代码之前需明确输入参数、该步骤的负责人以及结束标准。操作人员应能够从已知的检查点重新运行该步骤，而无需猜测隐藏状态。 配置信息应置于应用程序代码之外。环境文件、密钥存储以及功能开关应集中存放于一个位置，以便操作人员无需查看整个流程即可进行审计。 对于涉及资金支出或修改生产数据的环节，必须经过人工审批。编译时的连接方式并不等同于业务流程的完整性。 在2 For bugs需求阶段，修改代码之前需明确输入参数、该步骤的负责人以及结束标准。操作人员应能够从已知的检查点重新运行该步骤，而无需猜测隐藏状态。 相较于庞大的脚本，应优先使用小型且可测试的单元。当某个步骤失败时，故障原因应能明确指向某个特定职责，而非整个复杂的流程。

def parse_timeout(value: str) -> float:
    if value.endswith("s"):
        return float(value[:-1])

    if value.endswith("m"):
        return float(value[:-1]) * 60

    return float(value)

250ms is interpreted incorrectly.

def test_parse_timeout_milliseconds():
    assert parse_timeout("250ms") == 0.25

uv run pytest tests/test_timeout.py -q

python -m pytest tests/test_timeout.py -q

def parse_timeout(value: str) -> float:
    if value.endswith("ms"):
        return float(value[:-2]) / 1000

    if value.endswith("s"):
        return float(value[:-1])

    if value.endswith("m"):
        return float(value[:-1]) * 60

    return float(value)

reported bug
    ↓
observed failure
    ↓
code change
    ↓
observed success

3. 为智能体提供入门手册

在完成“为智能体提供指导”这一阶段时，首先需写下相关合同条款：所需输入、成功标志以及部分失败时的处理方式。这样的检查清单能确保后续的代码修改保持一致性。 将这一阶段视为输入与验证后输出之间的契约。为相关文件命名，明确成功标准，杜绝默许部分完成的情况。 在成本较高的步骤之后设置检查点。当操作员重新尝试后续节点时，恢复流程不应再次调用相同的大型语言模型。

# Project

FastAPI backend + React frontend.

Python dependencies are managed with uv.

## Important directories

backend/app/api/       HTTP endpoints
backend/app/services/  business logic
frontend/src/features/ feature code
tests/                 backend tests

## Commands

Fast Python tests:

    uv run pytest -q tests/unit

Full verification:

    make verify

Development:

    make dev

## Working rules

Before editing:

1. Reproduce the problem.
2. Inspect the implementation involved.
3. Find similar existing code before creating a new pattern.
4. Identify or add a test.

Before completion:

1. Run relevant tests.
2. Run `make verify`.
3. Inspect `git diff`.
4. Report exactly what was verified.

Fast Python tests:
    python -m pytest -q tests/unit

4. 将反复出现的经验转化为技能

在完成4轮循环课程阶段时，首先写下相关约定：所需输入、成功标志以及部分失败时的处理方式。这样的检查清单能确保后续的代码修改保持一致性。 在功能结果旁记录执行时间以及令牌或查询成本。提前明确成本有助于避免从演示环境过渡到共享环境时出现意外费用。 在耗时较高的步骤之后设置检查点。当操作员重新尝试后续节点时，恢复流程不应再次收取相同的LLM调用费用。

skills/debug-with-evidence/SKILL.md

# Debug with evidence

Before modifying production code:

1. Capture the exact symptom.
2. Reproduce it.
3. Find the narrowest failing case.
4. Inspect the code actually executed.
5. Form hypotheses only after gathering evidence.
6. Prefer experiments that distinguish competing explanations.
7. Add a regression test when practical.
8. Make the smallest justified fix.
9. Rerun the reproduction.
10. Run full verification.

For Python projects managed by uv, run Python tools with `uv run`.

Report:

- observed failure
- root cause
- evidence
- files changed
- verification performed

#!/usr/bin/env bash
set -euo pipefail

echo "=== STATUS ==="
git status --short

echo
echo "=== RECENT COMMITS ==="
git log --oneline -10

echo
echo "=== DIFF ==="
git diff --stat

echo
echo "=== TESTS ==="
uv run pytest -q --tb=short

python -m pytest -q --tb=short

if rg 'app\.database' frontend/src
then
    echo "Frontend may not import app.database"
    exit 1
fi

"Don't import X here."
→ dependency check

"Every endpoint needs authorization."
→ middleware + test

"Don't forget to regenerate the schema."
→ CI check

"Every bug fix needs a regression test."
→ workflow rule

"Don't modify generated files."
→ generated-file check

uv run ruff check .
uv run mypy .
uv run pytest

python -m ruff check .
python -m mypy .
python -m pytest

6. 选择最简单的方案作为正确解

在完成“6个简化步骤”中的第一阶段时，首先要明确相关规范：所需的输入参数、成功标志以及部分失败时的处理方式。这样的清单能确保后续的代码修改保持一致性。 应将配置信息与应用程序代码分开存放。环境文件、密钥存储以及功能开关应集中管理，以便操作人员无需查看整个流程就能进行审计。 在耗时较高的步骤之后设置检查点。当操作人员重新尝试后续节点时，恢复流程不应再次调用相同的大型语言模型接口。 在完成“6个简化步骤”中的第一阶段时，首先要明确相关规范：所需的输入参数、成功标志以及部分失败时的处理方式。这样的清单能确保后续的代码修改保持一致性。 相比复杂的脚本，更应优先使用小型且可测试的单元。当某个步骤失败时，故障原因应能明确指向某个具体的功能模块，而非整个混乱的流程。

components/
services/
hooks/
types/
validation/
screens/

features/
├── billing/
│   ├── api.ts
│   ├── model.ts
│   ├── BillingPage.tsx
│   └── BillingPage.test.tsx
│
└── login/
    ├── api.ts
    ├── model.ts
    ├── LoginPage.tsx
    └── LoginPage.test.tsx

7. 使用新的审核人员

将“使用新审核人员”这一阶段视为可衡量的环节最为有效。在扩大范围之前，先记录一份优秀的处理结果、一个失败案例以及回滚说明。 应将此阶段视为输入与经过验证的输出之间的契约。为相关成果命名，明确成功标准，杜绝默许的半完成状态。 保持图结构简洁且类型明确。嵌套的数据块会掩盖哪个节点编写了哪个字段的信息，还会在中断后导致流程无法继续。

Agent A
    ↓
implements
    ↓
Agent B
    ↓
reviews from fresh context

Check:

1. Does the change actually satisfy the task?
2. Can you reproduce the original bug?
3. Are edge cases missing?
4. Were tests weakened?
5. Is there unnecessary complexity?
6. Are architectural boundaries violated?
7. Is existing functionality duplicated?
8. Do the tests verify behavior?

For Python changes, run the relevant checks yourself:

    uv run ruff check .
    uv run mypy .
    uv run pytest

python -m ruff check .
python -m mypy .
python -m pytest

confirmed defect
plausible concern
stylistic preference

8. 通过工作树实现并行处理，而非混乱操作

将“8. 使用工作树并行化”阶段视为可度量的对象来处理效果最佳。在扩大范围之前，先记录一份理想的转录结果、一个故障案例以及回滚说明。在功能测试结果旁同时记录执行时间以及令牌或查询成本。提前了解这些成本，就能避免在从演示环境过渡到共享环境时出现意外费用。要保持图结构的状态简洁且类型明确，嵌套的数据块会掩盖哪个节点修改了哪个字段的信息，还会在中断后导致无法继续执行。

git worktree add ../app-auth -b agent/auth
git worktree add ../app-search -b agent/search
git worktree add ../app-billing -b agent/billing

app-auth/
app-search/
app-billing/

uv sync
uv run pytest

python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
python -m pytest

Agent 1: investigate authentication bug
Agent 2: implement CSV export
Agent 3: profile search performance

Agent 1: refactor authentication
Agent 2: refactor authentication differently
Agent 3: rename files both others are editing

9. 将每一处人工修正都视为数据

“9个处理原则”指出，将每个业务阶段视为可度量的对象才能达到最佳效果。在扩大范围之前，需记录一份标准案例、一个故障实例以及回滚说明。 配置应与应用程序代码分开存放。环境文件、密钥存储和功能开关应集中于一处，以便操作人员无需查看整个系统结构即可进行审计。 保持系统状态的结构化与类型化。嵌套的数据结构会掩盖具体是哪个节点修改了哪个字段，还会导致中断后无法继续执行。 “9个处理原则”指出，将每个业务阶段视为可度量的对象才能达到最佳效果。在扩大范围之前，需记录一份标准案例、一个故障实例以及回滚说明。 相比庞大的脚本，应优先使用小型且可测试的单元。当某个步骤出现故障时，故障点应指向单一的责任模块，而非复杂的流程链。

Agent lacked project knowledge?
→ improve AGENTS.md

Agent didn't know the procedure?
→ create a Skill

Bug escaped?
→ regression test

Same architectural mistake again?
→ CI/static rule

Task was ambiguous?
→ improve task template

Agent trusted its own solution too easily?
→ independent reviewer

agent makes mistake
       ↓
human understands why
       ↓
lesson becomes process
       ↓
process becomes Skill/test/CI
       ↓
future agent avoids whole category of mistake

首先应构建的架构

在开始代码修改之前，需先规划好整个流程的架构，明确输入参数、各步骤的负责人以及结束标准。操作人员应能够从已知的检查点重新运行相应步骤，而无需猜测隐藏的状态。 应将这一阶段视为输入与经过验证的输出之间的契约。为相关成果命名，设定成功判定标准，杜绝默许部分完成的情况。 对于涉及资金支出或修改生产数据的操作，必须经过人工审批。仅靠编译时的配置并不能保证业务的完整性。

pyproject.toml
uv.lock
AGENTS.md
Makefile
scripts/verify.sh
skills/debug-with-evidence/SKILL.md
skills/review-change/SKILL.md

uv init

uv sync

uv add --dev pytest ruff mypy

uv run pytest
uv run ruff check .
uv run mypy .

pip install pytest ruff mypy

python -m pytest
python -m ruff check .
python -m mypy .

1. Investigate.
2. Reproduce.
3. Write failing test.
4. Implement smallest fix.
5. Run fast tests.
6. Run full verification.
7. Fresh agent reviews diff.
8. Human corrections become permanent rules.

Own this task end to end.

Before editing:
- inspect the relevant implementation,
- reproduce the problem,
- examine similar existing code.

During implementation:
- make the smallest coherent change,
- add or update tests,
- use `uv run` for Python tools,
- verify while iterating.

Before completion:
- run full verification,
- inspect the final diff,
- independently check the original requirement.

Report what changed, what was verified,
and any remaining uncertainty.

更宏观的思路

在“更大规模规划”阶段，应在修改代码之前明确输入参数、该步骤的负责人以及终止标准。操作人员应能够从已知的检查点重新运行该步骤，而无需猜测隐藏状态。除了功能结果外，还需记录执行时间以及令牌或查询成本。提前了解这些成本可以避免在从演示环境过渡到共享环境时出现意外费用。对于那些会耗费资金或修改生产数据的操作，必须经过人工审批。仅靠编译时的配置并不足以确保业务的完整性。

prompt → code

requirement
    ↓
agent
    ↓
code
    ↓
execution
    ↓
verification
    ↓
review
    ↓
feedback
    ↓
better Skills / tests / architecture
    ↺

uv run pytest tests/test_bug.py -q
uv run ruff check .
uv run mypy .
make verify

python -m pytest tests/test_bug.py -q
python -m ruff check .
python -m mypy .
make verify

操作检查清单

在处理操作检查清单阶段时，首先需明确相关约定：所需的输入参数、成功标志，以及部分失败时的处理方式。这样的检查清单能确保后续的代码修改保持透明可追溯。

应将正常流程和恢复流程一并记录下来。重试机制、人工干预环节以及死信处理都是产品本身的组成部分，而非后续才添加的完善措施。

在成本较高的操作之后设置检查点。当操作员重新尝试后续节点时，恢复功能不应再次计费相同的LLM调用费用。

锁定依赖版本的编号，并记录用于运行演示的镜像摘要。可重复性远比经验知识更重要。

优先选择小型且易于测试的单元，而非结构复杂的脚本。当某个步骤失败时，故障应能指向具体的责任模块，而非整个混乱的流程。

在成本较高的操作之后设置检查点。当操作员重新尝试后续节点时，恢复功能不应再次计费相同的LLM调用费用。

在推广该技术栈之前，应先冻结版本，为关键流程记录标准输出日志，并明确回滚步骤。共享环境需要设置速率限制、租户验证机制，以及负责密钥轮换的明确责任人。与其展示花哨的一次性演示，不如注重扎实的可靠性。

关于780e678b0ae3的批处理说明：请将提供商密钥移出代码仓库，设定单会话令牌上限，并将日志存储在评估用示例文件旁，以便后续模型更换时保持数据可比性。