mirror of
https://github.com/boshu2/agentops.git
synced 2026-09-14 15:08:13 +08:00
docs: surface behavioral discipline examples
This commit is contained in:
Boden Fuller
@@ -10,7 +10,7 @@
|
||||
|
||||
The operational layer for coding agents. AgentOps adds bookkeeping, validation, primitives, and flows so every session starts where the last one left off.
|
||||
|
||||
[Install](#install) · [See It Work](#see-it-work) · [Start Here](#start-here) · [What You Get](#what-agentops-gives-you) · [Skills](#skills) · [CLI](#the-ao-cli) · [FAQ](#faq) · [Docs](docs/INDEX.md) · [Newcomer Guide](docs/newcomer-guide.md)
|
||||
[Install](#install) · [See It Work](#see-it-work) · [Start Here](#start-here) · [Behavior](docs/behavioral-discipline.md) · [What You Get](#what-agentops-gives-you) · [Skills](#skills) · [CLI](#the-ao-cli) · [FAQ](#faq) · [Docs](docs/INDEX.md) · [Newcomer Guide](docs/newcomer-guide.md)
|
||||
|
||||
</div>
|
||||
|
||||
@@ -213,6 +213,35 @@ Full catalog: [docs/SKILLS.md](docs/SKILLS.md) · Unsure which skill to run? [Sk
|
||||
|
||||
---
|
||||
|
||||
## What Good Agent Behavior Looks Like
|
||||
|
||||
AgentOps is not only about chaining commands together. It also pushes agents toward better behavior during implementation and review.
|
||||
|
||||
```text
|
||||
User: "Make search faster"
|
||||
|
||||
Without behavioral discipline:
|
||||
- picks one interpretation silently
|
||||
- adds caching, async work, and config knobs
|
||||
- claims success when the code compiles
|
||||
|
||||
With AgentOps behavioral discipline:
|
||||
- clarifies whether "faster" means latency, throughput, or perceived speed
|
||||
- chooses the smallest change that matches that goal
|
||||
- verifies against the metric that actually mattered
|
||||
```
|
||||
|
||||
That same discipline shows up in four habits:
|
||||
|
||||
- **Think before coding** — surface assumptions and tradeoffs instead of guessing.
|
||||
- **Simplicity first** — solve the problem with the smallest change that works.
|
||||
- **Surgical changes** — keep the diff tight and avoid drive-by refactors.
|
||||
- **Goal-driven execution** — define proof before calling the work done.
|
||||
|
||||
See the full before/after guide: [docs/behavioral-discipline.md](docs/behavioral-discipline.md)
|
||||
|
||||
---
|
||||
|
||||
## What AgentOps Gives You
|
||||
|
||||
AgentOps gives your coding agent four things it does not have by default:
|
||||
|
||||
@@ -5,6 +5,7 @@
|
||||
## Getting Started
|
||||
|
||||
- [README](../README.md) — Project overview and quick start
|
||||
- [Behavioral Discipline](behavioral-discipline.md) — Before/after examples of good coding-agent behavior
|
||||
- [Newcomer Guide](newcomer-guide.md) — Fast orientation to repo structure, architecture, and contribution path
|
||||
- [FAQ](FAQ.md) — Comparisons, limitations, subagent nesting, uninstall
|
||||
- [CONTRIBUTING](CONTRIBUTING.md) — How to contribute
|
||||
|
||||
@@ -0,0 +1,105 @@
|
||||
# Behavioral Discipline
|
||||
|
||||
AgentOps does not just add orchestration. It also pushes coding agents toward better behavior.
|
||||
|
||||
The core idea is simple: good agents do not silently assume, overbuild, wander outside scope, or declare victory without proof. This page shows what that means in practice.
|
||||
|
||||
## The Four Behaviors
|
||||
|
||||
| Behavior | What it prevents |
|
||||
|---|---|
|
||||
| **Think before coding** | hidden assumptions, silent confusion, wrong interpretation |
|
||||
| **Simplicity first** | bloated abstractions, speculative flexibility, oversized patches |
|
||||
| **Surgical changes** | drive-by refactors, unrelated edits, noisy diffs |
|
||||
| **Goal-driven execution** | weak verification, "looks done" changes, proof by assertion |
|
||||
|
||||
AgentOps enforces this through the behavioral discipline standard in [`skills/standards/references/behavioral-discipline.md`](../skills/standards/references/behavioral-discipline.md), and through the active `/implement` and `/review` skill flows.
|
||||
|
||||
## Before/After Examples
|
||||
|
||||
### 1. Ambiguous Request
|
||||
|
||||
**User request:** "Make search faster"
|
||||
|
||||
**Before**
|
||||
|
||||
- The agent silently chooses one meaning of "faster"
|
||||
- It adds caching, async work, and extra config knobs
|
||||
- It ships a larger patch than the question justified
|
||||
|
||||
**After**
|
||||
|
||||
- The agent asks whether "faster" means latency, throughput, or perceived speed
|
||||
- It chooses the smallest change that matches the answer
|
||||
- It verifies against the metric that actually mattered
|
||||
|
||||
**Why this is better:** the work is driven by the real goal, not by the agent's guess.
|
||||
|
||||
### 2. Overbuilt Solution
|
||||
|
||||
**User request:** "Add a discount helper"
|
||||
|
||||
**Before**
|
||||
|
||||
- The agent creates strategy objects, factories, and multiple extension points
|
||||
- It adds flexibility nobody asked for
|
||||
- The code becomes harder to understand than the problem itself
|
||||
|
||||
**After**
|
||||
|
||||
- The agent starts with a small helper such as `calculate_discount(amount, percent)`
|
||||
- It adds complexity only when the requirement actually expands
|
||||
- The patch stays proportional to the problem
|
||||
|
||||
**Why this is better:** complexity should be earned by requirements, not imagined in advance.
|
||||
|
||||
### 3. Drive-By Editing
|
||||
|
||||
**User request:** "Fix empty emails crashing the validator"
|
||||
|
||||
**Before**
|
||||
|
||||
- The agent rewrites adjacent validation logic
|
||||
- It changes comments, formatting, and unrelated username rules
|
||||
- The diff is noisy and hard to review
|
||||
|
||||
**After**
|
||||
|
||||
- The agent adds a reproducer for the empty-email case
|
||||
- It fixes only the email path and only the cleanup caused by that fix
|
||||
- Unrelated problems are noted separately instead of bundled into the patch
|
||||
|
||||
**Why this is better:** every changed line maps to the stated goal.
|
||||
|
||||
### 4. Weak Proof
|
||||
|
||||
**User request:** "Improve this AgentOps skill"
|
||||
|
||||
**Before**
|
||||
|
||||
- The agent edits the skill text and says it is done
|
||||
- It skips the mirrored Codex artifact or does not validate it
|
||||
- The repo gets instruction drift
|
||||
|
||||
**After**
|
||||
|
||||
- The agent updates the shared skill contract and the checked-in Codex copy
|
||||
- It regenerates the affected hash metadata when needed
|
||||
- It runs the relevant validation commands before claiming completion
|
||||
|
||||
**Why this is better:** completion is defined by evidence, not by the existence of an edit.
|
||||
|
||||
## What to Look For in a Good Agent Diff
|
||||
|
||||
- The request is restated clearly before coding starts.
|
||||
- Ambiguity is surfaced instead of silently resolved.
|
||||
- The patch is smaller than the first idea, not larger.
|
||||
- Unrelated files stay untouched.
|
||||
- The verification matches the behavior that was changed.
|
||||
|
||||
## Where This Lives in AgentOps
|
||||
|
||||
- [`README.md`](../README.md) gives the front-door version.
|
||||
- [`skills/implement/SKILL.md`](../skills/implement/SKILL.md) requires an execution frame before editing.
|
||||
- [`skills/review/SKILL.md`](../skills/review/SKILL.md) checks for hidden assumptions, speculative abstractions, and weak proof.
|
||||
- [`skills/standards/references/behavioral-discipline.md`](../skills/standards/references/behavioral-discipline.md) is the reusable reference that the skills load.
|
||||
@@ -862,7 +862,7 @@
|
||||
"name": "standards",
|
||||
"source_skill": "skills/standards",
|
||||
"source_hash": "837a4c5f624c5de7dbe37193fb1671a97d2f4c9381355c4b3745e247b632577a",
|
||||
"generated_hash": "23b155149199a2a717809385cafdcd75214b7e1bfcbe4e47a8e666e5319068dc"
|
||||
"generated_hash": "33afeca1a2dc5ba35f1fec148563937f4730d83f17b414cf71e2c40cfab5b68b"
|
||||
},
|
||||
{
|
||||
"name": "status",
|
||||
|
||||
@@ -3,5 +3,5 @@
|
||||
"source_skill": "skills/standards",
|
||||
"layout": "modular",
|
||||
"source_hash": "837a4c5f624c5de7dbe37193fb1671a97d2f4c9381355c4b3745e247b632577a",
|
||||
"generated_hash": "23b155149199a2a717809385cafdcd75214b7e1bfcbe4e47a8e666e5319068dc"
|
||||
"generated_hash": "33afeca1a2dc5ba35f1fec148563937f4730d83f17b414cf71e2c40cfab5b68b"
|
||||
}
|
||||
|
||||
@@ -72,6 +72,69 @@ Turn requests into verifiable outcomes.
|
||||
- "Improve this skill" becomes "update the contract, validate skill integrity, then check the shipped runtime copy."
|
||||
- "Clean up the hook" becomes "preserve the contract, edit only the required files, then run the hook/doc parity gate."
|
||||
|
||||
## Before/After Examples
|
||||
|
||||
### Example 1: Hidden Assumptions
|
||||
|
||||
**Request:** "Make search faster"
|
||||
|
||||
**Before**
|
||||
|
||||
- picks one meaning of "faster" without clarifying
|
||||
- adds caching, async work, and new knobs all at once
|
||||
- verifies only that the code still runs
|
||||
|
||||
**After**
|
||||
|
||||
- asks whether "faster" means latency, throughput, or perceived speed
|
||||
- picks the smallest change that matches the answer
|
||||
- verifies against the metric that actually mattered
|
||||
|
||||
### Example 2: Overbuilt Solution
|
||||
|
||||
**Request:** "Add a discount helper"
|
||||
|
||||
**Before**
|
||||
|
||||
- introduces strategies, factories, and extension points for a one-off need
|
||||
- adds flexibility nobody asked for
|
||||
|
||||
**After**
|
||||
|
||||
- starts with a small helper that solves the current requirement
|
||||
- defers abstraction until a real second use case exists
|
||||
|
||||
### Example 3: Drive-By Editing
|
||||
|
||||
**Request:** "Fix empty emails crashing the validator"
|
||||
|
||||
**Before**
|
||||
|
||||
- rewrites adjacent validation logic
|
||||
- edits comments and formatting unrelated to the bug
|
||||
- leaves a large diff for a narrow request
|
||||
|
||||
**After**
|
||||
|
||||
- adds a reproducer for the empty-email case
|
||||
- fixes only the email path plus cleanup caused by that fix
|
||||
- records unrelated cleanup separately instead of bundling it into the patch
|
||||
|
||||
### Example 4: Weak Proof
|
||||
|
||||
**Request:** "Improve this AgentOps skill"
|
||||
|
||||
**Before**
|
||||
|
||||
- edits the skill doc and stops
|
||||
- forgets the mirrored Codex artifact or validation step
|
||||
|
||||
**After**
|
||||
|
||||
- updates the shared contract and the checked-in Codex copy
|
||||
- regenerates affected artifact metadata when needed
|
||||
- runs the relevant validation commands before claiming completion
|
||||
|
||||
## Review Questions
|
||||
|
||||
Use these four questions when validating a plan, patch, or PR:
|
||||
|
||||
@@ -72,6 +72,69 @@ Turn requests into verifiable outcomes.
|
||||
- "Improve this skill" becomes "update the contract, validate skill integrity, then check the shipped runtime copy."
|
||||
- "Clean up the hook" becomes "preserve the contract, edit only the required files, then run the hook/doc parity gate."
|
||||
|
||||
## Before/After Examples
|
||||
|
||||
### Example 1: Hidden Assumptions
|
||||
|
||||
**Request:** "Make search faster"
|
||||
|
||||
**Before**
|
||||
|
||||
- picks one meaning of "faster" without clarifying
|
||||
- adds caching, async work, and new knobs all at once
|
||||
- verifies only that the code still runs
|
||||
|
||||
**After**
|
||||
|
||||
- asks whether "faster" means latency, throughput, or perceived speed
|
||||
- picks the smallest change that matches the answer
|
||||
- verifies against the metric that actually mattered
|
||||
|
||||
### Example 2: Overbuilt Solution
|
||||
|
||||
**Request:** "Add a discount helper"
|
||||
|
||||
**Before**
|
||||
|
||||
- introduces strategies, factories, and extension points for a one-off need
|
||||
- adds flexibility nobody asked for
|
||||
|
||||
**After**
|
||||
|
||||
- starts with a small helper that solves the current requirement
|
||||
- defers abstraction until a real second use case exists
|
||||
|
||||
### Example 3: Drive-By Editing
|
||||
|
||||
**Request:** "Fix empty emails crashing the validator"
|
||||
|
||||
**Before**
|
||||
|
||||
- rewrites adjacent validation logic
|
||||
- edits comments and formatting unrelated to the bug
|
||||
- leaves a large diff for a narrow request
|
||||
|
||||
**After**
|
||||
|
||||
- adds a reproducer for the empty-email case
|
||||
- fixes only the email path plus cleanup caused by that fix
|
||||
- records unrelated cleanup separately instead of bundling it into the patch
|
||||
|
||||
### Example 4: Weak Proof
|
||||
|
||||
**Request:** "Improve this AgentOps skill"
|
||||
|
||||
**Before**
|
||||
|
||||
- edits the skill doc and stops
|
||||
- forgets the mirrored Codex artifact or validation step
|
||||
|
||||
**After**
|
||||
|
||||
- updates the shared contract and the checked-in Codex copy
|
||||
- regenerates affected artifact metadata when needed
|
||||
- runs the relevant validation commands before claiming completion
|
||||
|
||||
## Review Questions
|
||||
|
||||
Use these four questions when validating a plan, patch, or PR:
|
||||
|
||||
Reference in New Issue
Block a user