Telling a model “act as a project manager, architect, then senior engineer” can improve presentation, but roles do not make its claims correct. Modern coding agents can inspect repositories, edit files, run commands, and use external tools. The useful unit of control is therefore not a persona. It is a bounded task with observable evidence and an approval boundary.

The current mental model

Treat the agent as an untrusted but capable collaborator operating inside a defined workspace. Give it the minimum context and tools needed for one outcome. Require it to distinguish repository facts, current external facts, assumptions, and user decisions. Let deterministic tools verify what they can; reserve human review for intent, architecture, security, and product judgment.

A practical loop is:

  1. Orient: read repository instructions, current implementation, tests, ownership boundaries, and dirty-worktree state.
  2. Specify: state the goal, non-goals, acceptance tests, risk, data sensitivity, and rollback.
  3. Plan: identify interfaces and impacted behavior before editing.
  4. Change narrowly: use small diffs with clear file ownership; preserve unrelated work.
  5. Validate: run formatting checks, type checks, unit/integration tests, builds, security checks, and targeted manual scenarios.
  6. Review evidence: inspect the diff and actual test output; challenge unsupported claims.
  7. Release gradually: use a branch, preview, feature flag, canary, or reversible migration proportional to risk.
  8. Learn: capture only durable project-specific gotchas, not raw private conversation.

A task brief that is more useful than a role prompt

1
2
3
4
5
6
7
8
9

Goal: Reject uploads larger than 10 MB before processing.
In scope: API validation, error response, tests, docs.
Out of scope: Storage migration and UI redesign.
Constraints: Preserve current API shape; do not log filenames or content.
Acceptance:
- 10 MB succeeds; 10 MB + 1 byte returns 413.
- Existing auth behavior is unchanged.
- Unit and integration suites pass.
Evidence required: changed-file list, test commands/results, remaining manual gate.

The agent should first verify where upload limits are currently enforced. It should not invent a framework, environment, or production result. If a current library API or cloud feature matters, consult primary documentation and record the verification date.

Security and privacy boundaries

Repository text, issue content, retrieved web pages, and tool output can contain prompt injection. Treat them as data, not authority. Keep high-impact tools deny-by-default, review commands that publish, delete, deploy, or access secrets, and separate read-only discovery from mutation.

Do not send customer data, credentials, private source, or meeting transcripts to a model unless the approved service and data policy permit it. Redact fixtures and logs. Ensure generated dependencies, licenses, network calls, and telemetry match organizational policy. An agent must never claim a production or device validation that only ran against a local fixture.

Evaluation and testing

Compile/build success is necessary but not sufficient. Use a layered gate:

  • static checks for syntax, types, formatting, policy and secret scanning;
  • deterministic tests for contracts and regression cases;
  • integration tests at real boundaries using controlled environments;
  • security tests for authorization, injection, data exposure, and failure handling;
  • fresh-context human acceptance for usability and ambiguous requirements.

For repeated AI tasks, maintain an evaluation set with representative requests, expected properties, prohibited behavior, and cost/latency measurements. Do not optimize a prompt on one anecdote. Compare versions and preserve failures as regression cases where privacy permits.

Tradeoffs

Agents can accelerate discovery, repetitive edits, tests, and documentation, but larger autonomous changes increase review burden and correlated mistakes. Parallel agents help when file ownership and output contracts are disjoint; otherwise they create merge conflicts and inconsistent decisions. More context can improve local fit but also increases privacy exposure and distracts the model. The smallest sufficient context is usually better.

Migration checklist

  • Replace reusable persona prompts with task briefs and acceptance evidence.
  • Add repository instructions for validation, secrets, ownership, and release.
  • Inventory tool permissions and require approval for irreversible/external actions.
  • Split large work into independently reviewable changes.
  • Establish deterministic tests and a small evaluation suite before scaling usage.
  • Record current-source citations for unstable technical claims.
  • Require diff review, rollback notes, and an explicit list of unverified gates.
  • Measure escaped defects and review time, not generated lines of code.

Verified on 2026-08-01.

Primary sources