What AI-assisted development setup should an experienced developer use when starting a new project?

The principle that keeps the setup useful

An AI coding tool can speed up exploration and implementation. It cannot own the architecture, security posture, operational duty, or quality bar. The developer and team still own those things because they understand the product consequences and must support the software after the generated text is forgotten.

Build the project so that a capable new human engineer could succeed with a fresh clone and the standard toolchain. Then make that same information legible to an assistant. This produces better AI results, but more importantly it reduces onboarding time, review ambiguity, and dependence on a single vendor.

Use five durable layers:

1. Intent: a concise problem statement, success measures, non-goals, and important constraints.
2. Boundaries: architecture notes, data flows, trust boundaries, threat model, and explicit ownership of external systems.
3. Executable truth: build commands, tests, types, linters, migrations, local fixtures, and a fast way to validate one change.
4. Controlled delegation: repository instructions, least-privilege permissions, narrow tasks, approval points, and reviewable diffs.
5. Feedback: CI results, production observability, cost and usage data, incident learnings, and a pilot scorecard.

The order matters. Adding more agents before the first three layers simply lets an assistant produce more unverified changes faster.

Start with discovery before scaffolding

Before choosing a framework or prompting an agent to generate a skeleton, write three short documents. They can be rough on day one, but they must name the decisions that code would otherwise hide.

Do this with or without AI. Chat is useful here as a critic: ask it to enumerate assumptions, alternative designs, failure modes, and abuse cases. Do not accept its architecture as a design decision merely because it sounds coherent. Compare its claims with project constraints, provider documentation, and the judgment of the engineer who will operate the system.

The OWASP threat-modeling guidance frames the exercise around four questions: what are we building, what can go wrong, what will we do about it, and did we do enough. It also recommends reviewing the model with stakeholders, not only developers. OWASP Threat Modeling Cheat Sheet Put resolved threats into acceptance criteria and automated checks where possible. A note that no test can enforce is still valuable, but it needs a named review owner.

Define a first vertical slice

Choose one narrow end-to-end journey, such as "an authenticated user creates a project and can read it back." Write its contract before asking an agent to implement it: request and response shape, authorization rule, expected errors, persistence behavior, logs or metrics, and tests. This prevents a new-project agent session from building five loosely connected subsystems before any behavior can be verified.

The first slice is also the right place to decide whether AI is a product dependency or only a development aid. If the service itself calls a model, document data sent to the provider, cost budget, timeout, failure fallback, and human-review boundary. A development assistant's convenience does not justify sending customer data into an unapproved context.

Make repository context portable and testable

Put instructions in version control, not in a developer's personal prompt history. A root AGENTS.md is a practical vendor-neutral convention, but the exact filename is less important than its content and review history. Keep it short enough that an agent can use it reliably, and link to detailed documents instead of duplicating the entire handbook.

Current examples confirm the portability problem. As of 2026-09-01, GitHub Copilot supports repository-wide, path-specific, and agent instruction files, including AGENTS.md, while other tools use their own conventions. GitHub custom-instructions reference Write the project facts once in ordinary Markdown, then add a thin tool-specific adapter only where needed.

Example repository instruction file

This example is deliberately small. Replace bracketed choices with facts that the team has verified.

# Repository instructions

Purpose and boundaries

• This service manages [resource] for [user type].
• Treat authentication, authorization, billing, data deletion, and external webhooks as security-sensitive.
• Read docs/problem.md, docs/architecture.md, and docs/threat-model.md before changing a boundary.

Working rules

• Make the smallest change that satisfies the accepted task. Do not refactor unrelated code.
• Never print, copy, commit, or transmit secrets. Use .env.example and test fixtures only.
• Do not add a dependency, change a schema, or alter deployment configuration without stating why in the pull request.
• Do not call production systems, deploy, merge, rotate credentials, or change access controls.

Validation

• Run make check before proposing a change.
• Add or update a focused test for behavior changes.
• Run the integration test target for API, storage, or authentication changes.
• Report the files changed, commands run, test results, and unresolved risks.

Review focus

• Check input validation, authorization on every server-side operation, error handling, migrations, and observability.
• Flag ambiguity instead of inventing product or security policy.

An instruction file is not a security boundary. Agents can misunderstand it, and untrusted text in issues, pull requests, documentation, websites, or tool output can try to redirect the agent. OWASP specifically identifies indirect prompt injection in development workflows and recommends dependency auditing for AI-suggested packages. [OWASP Secure Coding with AI](https://cheatsheetseries.owasp.org/cheatsheets/Secure_Coding_with_AI_Cheat_Sheet.html) Use instructions to reduce routine mistakes, then enforce important rules through permissions, CI, branch protection, and human review.

### Keep context boundaries clear

Give an assistant the smallest set of files, tickets, logs, and documents that it needs for the present task. Long context is not automatically better. It can hide the true requirement, include stale design decisions, cost more, and increase the chance that a secret or hostile instruction enters the session.

Use a task packet for delegated work:

- goal and non-goals;
- files and APIs in scope;
- acceptance criteria and test command;
- relevant architecture or threat-model link;
- explicit permissions, such as read-only, edit only, or run tests in a disposable environment;
- stop conditions, including when the agent must ask rather than choose.

Version the packet when it matters. If a task produces an incident, a review dispute, or an unexpectedly expensive run, you should be able to see which requirements, agent configuration, tool access, and model were used. Do not record customer secrets or raw sensitive data simply to make a prompt replayable.

Match the AI mode to the task

The highest-leverage setup does not delegate every task. It makes deliberate choices about the degree of autonomy and the evidence needed to trust an answer.

Model selection should follow the same table. Use a fast, inexpensive model for autocomplete and low-risk transformations. Use a stronger reasoning model for architecture critique, hard debugging, or review of a bounded diff. Use a research-capable model only where browsing and citations are actually needed. Keep a smaller fallback model or non-AI workflow for outage and cost control, but do not silently substitute it on a security-sensitive task without re-evaluating its output.

As a dated example rather than a workflow requirement, OpenAI describes Codex as a coding agent usable in local tools or a cloud sandbox, and says its work can be reviewed before merge or deployment. OpenAI Codex overview, current as of 2026-09-01 GitHub likewise documents code-review and agent custom instructions that vary by environment. GitHub custom instructions These are examples of categories, not a reason to design the project around one vendor.

Choose local, hosted, or hybrid deliberately

"Local" can mean a local editor plugin calling a hosted model, a command-line agent with local file access, or a model actually running on your machine. Ask separately where inference runs, where code and prompts are processed, what network access the agent has, and whether the provider retains or trains on the data under the applicable agreement.

For any hosted path, use organization-approved accounts, understand retention and data-control terms, and deny access to source directories or credentials that the task does not need. For any local path, do not mistake local inference for automatic safety: a local agent can still damage a workspace, leak secrets through enabled network tools, or install a compromised dependency.

The practical default for a greenfield service is hosted inference with a local repository checkout, read-only exploration, and narrow write permissions. Revisit the decision after the pilot has real evidence about data sensitivity, accuracy, latency, cost, and the amount of developer time spent operating the tool.

Set permissions before enabling autonomy

Use least privilege by default. The permission model should distinguish reading a repository, editing a scoped worktree, running tests, accessing the network, reading secrets, modifying cloud resources, and causing external effects. Those are not interchangeable capabilities.

Keep production credentials out of the development agent environment. Use an .env.example with placeholders, test identities, local emulators, short-lived scoped credentials, and separate cloud accounts. Secret scanning is still useful, but it is not a guarantee because transformed or emitted values can evade masking. GitHub's secure-use guidance explicitly warns that automatic redaction is not guaranteed and recommends reviewing workflow logs. GitHub Actions secure use

Avoid attaching arbitrary tool servers, browser extensions, or remote connectors to an agent during the first week. Every connector widens the prompt-injection and credential boundary. Start with repository files and local tests. Add one trusted integration only when it removes a recurring, measurable bottleneck and has an owner, access policy, audit trail, and removal plan.

Make quality gates the agent's feedback loop

An agent gives better results when it can run the same checks a human would run, but the checks need to exist before the agent is told to fix them. Scaffold the project around a single developer command, such as make check or just check, that runs formatting, linting, type checking, unit tests, and any fast static security scan.

For a typed small web service, establish these early:

• formatter and linter with a committed configuration;
• strict type checking at the application boundary;
• unit tests for business rules and pure transformations;
• integration tests for the HTTP API, persistence, authentication, and migrations;
• a local fixture or ephemeral test database that never needs production data;
• contract tests for external APIs and recorded failure cases;
• a production-like build and a health check;
• structured logs, request IDs, error reporting, basic latency and error-rate metrics.

Generated tests deserve the same scrutiny as generated production code. An agent can create a test that merely confirms its own implementation. Review whether the test would fail for a meaningful defect, especially around authorization, validation, retries, error cases, race conditions, and data deletion.

Use security scanning as a gate and a prioritization aid, not a replacement for review. GitHub's dependency review can report vulnerable dependency changes introduced in pull requests, including configurable severity and license policies. GitHub dependency review Pair it with a dependency policy: approve a new package only with a named purpose, maintained version, license fit, lockfile diff, security scan, and removal owner. Prefer existing platform capability over a new package whose only benefit is a generated convenience wrapper.

The OWASP secure-code-review guidance emphasizes that automated scanning complements, rather than replaces, human assessment of business logic, data flow, and context-specific weaknesses. OWASP Secure Code Review Keep protected branches and require passing CI plus an accountable reviewer before merge, even when an AI review bot has commented.

Observe the workflow and control its cost

Treat AI-assisted development as an observable part of the engineering system. For each delegated task, record a task ID, repository and commit, changed paths, model or agent configuration, permission level, tools used, commands run, elapsed time, token or credit cost where available, CI outcome, review outcome, and rework or rollback. Store links and hashes rather than raw source, prompts, or secrets unless a documented data-handling rule authorizes the content.

This record helps distinguish four different problems: the task was underspecified, the context was stale, the tool made a bad change, or the project controls failed to catch it. It also makes a pilot measurable. Basic service telemetry remains separate but linked: request IDs, errors, latency, deployment version, and user-impacting incidents should show whether generated changes helped or harmed the running system.

Set budgets at several levels: an individual exploratory session, a delegated task, a developer or team month, and any AI feature shipped to customers. Default to a cheaper model or autocomplete for routine work, set context and output caps, bound retries and agent loops, and require explicit approval for unusually expensive research or long-running delegation. Do not blend development-tool spending with product-model spending, because they have different owners and failure modes.

Provider estimates can change with model, task size, and context. For example, GitHub documents that its code-review consumption grows with pull-request size and repository custom instructions, and that ranges can evolve with models. GitHub Copilot code review Use provider reporting for reconciliation, but make local task budgets and alerts visible before the monthly invoice arrives.

Review generated code as owned code

The person who merges a change owns its behavior, security, maintenance burden, and licensing consequences. "The agent wrote it" is not a useful root cause or an acceptable review explanation.

Keep generated diffs small enough to understand. Ask the agent to state the intent, files changed, assumptions, tests run, untested paths, dependencies added, and security-sensitive effects. A reviewer should inspect the diff before the summary, trace any change at a trust boundary, and rerun or require CI for the relevant checks.

For higher-risk changes, use a two-pass review: first, a human or automated reviewer checks whether the change implements the stated task and stays in scope; second, a reviewer with domain knowledge checks security, failure behavior, migrations, operational effects, and rollback. An AI code review can find issues and reduce routine review load, but it must remain an additional signal. OpenAI's current Codex guidance likewise says developers should review agent work before production changes and deployments. OpenAI Codex upgrades

Do not ask an agent to resolve its own security review finding by default. Treat the review comment as untrusted input, understand the issue, and assign the remediation as a separate bounded task. This reduces the chance that a malicious issue or pull-request comment turns into an instruction to weaken a control or make unrelated changes.

A practical first week for a small web service

This plan assumes one or two experienced developers building an internal or customer-facing service with an ordinary web API and database. Adjust the security and review depth upward for regulated data, payments, healthcare, children, authentication providers, or production infrastructure.

Do not measure success by lines generated or number of agent tasks. Measure cycle time from accepted task to reviewed, passing change; review time per change; rework or rollback rate; escaped defects; build and test reliability; secret or policy incidents; and the cost of both inference and human attention. Compare a pilot against the team's previous baseline for comparable work, not against a fantasy of fully autonomous delivery.

Avoid premature agent complexity

Multiple specialized agents, elaborate tool routing, long-lived memory, automatic issue triage, and write-enabled external connectors can be useful later. They are a poor starting point when the service has no stable architecture, tests, or operational runbook.

Add complexity only after a repeated task meets four tests:

1. The task is common enough that manual repetition is a real cost.
2. Its inputs, expected output, and failure conditions can be written down.
3. The tool has a safe permission boundary and a human escalation path.
4. The pilot data shows improvement without unacceptable review, reliability, security, or cost regressions.

For example, a weekly dependency-update pull request may eventually justify a delegated agent with restricted write access and mandatory CI. An agent that can read incident systems, edit production configuration, and merge its own changes does not follow from that success. The authority should grow more slowly than the automation capability.

Preserve an escape path

Treat every agent as replaceable. Keep source, prompts that encode essential project knowledge, test cases, lint configurations, build scripts, CI workflows, architecture notes, and deployment procedure in the repository or other organization-controlled systems. Do not make a proprietary chat history the only place where a migration rationale or runbook exists.

Use standard interfaces where practical: Git branches and pull requests for changes, shell commands or task runners for validation, normal package manifests and lockfiles, machine-readable API contracts, environment-variable-based configuration, and standard logs and metrics. Export task history and important review artifacts periodically if the chosen tool allows it.

When a tool changes price, capabilities, privacy terms, or disappears, the replacement process should be straightforward: run a short evaluation set against the same bounded tasks, port the repository instruction adapter, keep permissions at the lowest level, compare CI and review outcomes, and roll back to editor, terminal, and human review if the result is not good enough. That is more resilient than building an application-specific workflow around opaque agent memory.