# Make AI-assisted development produce checkable results

Canonical page: https://yishto.com/en/learn/product-building/specifications-and-coding-agents/

Author: [Yishto](https://yishto.com/en/about/)

Define behavior, permissions, and failure checks for export, then review AI development through small diffs, durable checkpoints, and a complete acceptance matrix.

Published: 2026-11-10
Updated: 2026-11-10

A coding agent can quickly produce a change for “add document export.” The harder task is verifying scope, permissions, and recovery. Specifications define observable behavior; development records diffs, checks, and recovery points for review.

The fictional export includes only the user's selected notes, preserving order and excluding unauthorized data. The example validates acceptance results without running an agent or export service.

## Specify behavior and failure

Define inputs, outputs, permissions, size limits, and errors. IDs select notes, fields are fixed, order is preserved, and invalid IDs fail explicitly. Larger work may use queryable jobs. Partial files must not appear fully successful unless partial results are intentionally supported and marked.

State non-goals and existing constraints. Avoid prescribing every function unless compatibility or security requires it. Useful detail lets implementers identify boundaries and reviewers observe results.

Connect requirements to evidence: ordered IDs, cross-user denial, and controlled timeouts. General quality instructions do not define completion.

## Gather context before changing code

Read relevant interfaces, tests, repository rules, and current edits. Use a branch or worktree where appropriate and retain a recoverable starting point. Separate directories may still share databases and external services, requiring their own restrictions.

Provide task context, relevant files, edit scope, and checks. Keep sensitive configuration out of prompts and logs. Investigate missing interfaces instead of guessing their contents.

Make small changes: serialization, permission queries, then job state and UI. Each step needs a diff and checks. Larger work needs ownership and dependencies so unrelated behavior is not rewritten accidentally.

## Compare agent reports with evidence

Tool capabilities depend on the product and permissions. A completion report must match the diff, command status, and test output. Mark unexecuted commands as pending.

Review each requirement's enforcement, normal and failure cases, unexpected deletions, dependencies, credentials, and permission expansion. A final summary alone can hide scope.

When checks fail, distinguish code defects, incorrect expectations, and environment issues. Preserve the failure and repair; do not delete tests to obtain green output. Run affected checks and expand only when unresolved concerns justify it.

## Give long tasks durable checkpoints

Record the objective, step, files, open issues, evidence, and recovery point. Continuation needs actual state rather than a conversational promise. Keep records consistent with files.

Bound retries and verification. Repeated failures need analysis instead of random edits. Record external blockers and continue independent work. Decisions should expose concrete results and missing information.

Code rollback does not undo database writes, files, or remote effects. Define failed-asset cleanup, retries, and duplicate prevention separately.

## Use multiple agents with explicit ownership

Parallel investigation or independent modules can help, while coordination, context, and merging add cost. Specify outputs, files, dependencies, and review order. Concurrent edits to one file can overwrite behavior; agent count does not establish correctness.

Claude Code documentation describes agent teams as experimental and disabled by default, with coordination and resumption limits. Verify current conditions instead of treating this as a stable universal feature. Subagents, sessions, and teams differ.

Remote Control continues a local session from another device rather than establishing cloud execution. Identify the execution machine separately from the remote entry point and check authentication, permission, and availability.

## Review skills and connected tools

Skills package instructions and scripts; MCP connects capabilities. Both can introduce code and permissions. Review provenance, scope, and user authorization instead of allowing embedded instructions to approve external writes.

Superpowers describes composable skills and a development workflow. Such conventions guide implementation without guaranteeing factual correctness. Select useful parts and retain actual execution evidence.

## Reject missing or ambiguous checks

The matrix requires normal, invalid-input, permission-denied, and timeout results. Every result must be boolean True; a string cannot establish success.

```python
required = {"normal", "invalid_input", "permission_denied", "timeout"}
results = {"normal": True, "invalid_input": True, "permission_denied": False}
def ready(checks):
    return required <= set(checks) and all(checks[name] is True for name in required)
assert not ready(results)
results.update(permission_denied=True, timeout=True)
assert ready(results)
assert not ready(dict(results, timeout="passed"))
print(ready(results))
```

The actual output is `True`. The initial missing timeout and failed permission check block completion. Complete results pass, while a string result fails. The matrix cannot prove tests ran; each True still needs its input, command, and output.

Link requirements, diffs, tests, and review through an issue or PR. Describe final behavior and limits and verify artifact and environment identities. Required unexecuted checks remain pending; release permission follows authorization and environment rules.

When accepting another agent's result, retain its scope and evidence source. A claim that a test passed without commands, inputs, or output remains unverified. Check dependencies and file conflicts before integration, then run affected checks. An isolated task report cannot establish that the combined change still works. Record what the integrating reviewer actually examined instead of relabeling the author's report as an independent review.

## Exercise: make export reviewable

Specify export and split serialization, permission, and job-state changes. Define edit scope, acceptance inputs, and recovery points. Simulate foreign IDs, wrong order, timeout, and omitted checks.

Accept the work when checks map to requirements, changes preserve scope, failures are explainable, and reports match execution. A checkpoint should let another developer resume from records. The matrix is one local rule; code correctness and release need their own evidence.

## Sources & further reading

- [Coding tool overview](https://code.claude.com/docs/en/overview)
- [Extend a coding tool with skills](https://code.claude.com/docs/en/skills)
- [Coordinate coding sessions with agent teams](https://code.claude.com/docs/en/agent-teams)
- [Remote development control](https://code.claude.com/docs/en/remote-control)
- [Structured coding workflow skills](https://github.com/obra/superpowers)
- [Pro Git](https://git-scm.com/book/en/v2)

Sources checked on 2026-11-10. Examples are teaching data, not production measurements.

## Related guides

- [AI agents and workflows: when to allow autonomous choices](https://yishto.com/en/learn/agents/workflows-and-agents/)
- [Support code evolution with tests and decision records](https://yishto.com/en/learn/data-practice/testing-refactoring-and-decisions/)