Set up a coding agent for a Next.js SaaS in five layers: repository instructions, task-specific skills, only the tools the task needs, enforced access limits, and checks that prove the change works. Start with project context and a small local task. Add external access when a concrete requirement justifies it.
This guide is for a solo developer who knows React and Next.js but has an agent with broad access, weak project knowledge, and no dependable finish line. The goal is a setup you can restart, review, and hand over. Its original assets are a layered setup diagram, a copyable task brief, and a setup-and-safety checklist.
The five layers of a practical agent setup
Each layer answers a different question. Instructions explain the project. Skills describe a procedure. Tools provide capabilities. Permissions constrain actions. Verification establishes what happened. Installing one layer does not supply the others.
REPOSITORY KNOWLEDGE
Architecture, conventions, commands, known limitations
|
v
TASK WORKFLOW
Relevant skill, existing implementation, acceptance cases
|
v
AVAILABLE TOOLS
Local files and shell; add a connector only when needed
|
v
ENFORCED ACCESS
Allowed paths, service scopes, network and write limits
|
v
COMPLETION EVIDENCE
Focused test, relevant checks, reviewed diff, unresolved limits
|
+---- confirmed correction back to repository knowledgeThis is a recommended operating model, not a diagram of one vendor's execution pipeline. Tool discovery and permission enforcement differ between clients. The useful invariant is that a remembered instruction cannot substitute for an access control, and an available command cannot substitute for its result.
Start with durable knowledge in the repository
Keep shared architecture decisions, provider boundaries, setup commands, and relevant limitations in version-controlled files. A future session and another developer should be able to find the same rules without reconstructing a conversation. Keep secrets, personal account settings, and temporary investigation notes outside that shared contract.
OpenAI's current documentation describes Codex reading AGENTS.md through a chain of global and project guidance, with more local files overriding earlier guidance. Check which files the session actually loaded, especially when you launch from a subdirectory. File names and discovery rules matter; a Markdown file's presence alone does not establish that the client used it.
Claude Code's documentation distinguishes persistent instruction files from automatically accumulated memory, and treats these as context. Its current documentation also covers AGENTS.md support. Check your installed client's behavior rather than assuming every version discovers files identically. Confirm the effective instruction sources in a fresh session.
A short contract is easier to maintain when it records decisions the agent cannot reliably infer: where business logic belongs, which code is shared, which changes require explicit scope, and which checks count. Link longer procedures rather than copying them into every instruction file. The earlier AGENTS.md template goes deeper into that document; this guide focuses on connecting it to the rest of the setup.
What the inspected Accelerator checkout establishes
On 4 October 2026, the inspected Frontend Accelerator product revision was 07c62151ba46984dccc67391e4624707d1a9509c. These are local source observations, not a test of every coding client or the deployed application.
- One engineering contract:
AGENTS.mddefines feature-first boundaries, Server Component defaults, provider adapters, protected infrastructure, and relevant verification commands. - Client entrypoints:
CLAUDE.md,.github/copilot-instructions.md,.cursor/rules/architecture.mdc, and.windsurfrulespoint back to the shared contract. Their existence does not prove a particular client loaded them. - Workflow resources:
.agents/skills/contains project skills, withskills-lock.jsontracking the installed set. Relevant areas include Next.js, testing, accessibility, and Stripe integration. - Verification commands:
package.jsondefinespnpm lint,pnpm test, andpnpm build. The build also has a sitemap postbuild step. A command being configured is not evidence that it passed. - MCP boundary: no project
.mcp.jsonor matching MCP JSON configuration appeared in the inspected file search. That does not establish what is configured in a developer's machine or account.
The interpretation is practical: this foundation gives an agent a place to learn the project's patterns. You still need to verify client discovery, configure access, and define the customer behavior your change must preserve.
Use skills for procedures, not permanent permission
A skill is useful when a task needs a repeatable sequence: inspect the existing payment boundary, identify the event behavior, add a focused regression case, and verify the resulting change. General architecture belongs in the shared contract; a specialist procedure belongs in the relevant workflow resource.
Both the current OpenAI and Claude Code documentation describe skills built around SKILL.md, with supporting resources or scripts when appropriate. Discovery locations and invocation controls are client-specific. Confirm that the intended skill is available before treating the workflow as active.
For your first task, choose one relevant procedure rather than loading the whole catalog. Read any script before execution and check whether it installs dependencies, contacts a service, edits files, or publishes something. A skill can request those actions; it does not establish that the task authorized them or that your account should permit them.
Use the existing SaaS skills guide for individual workflow examples. The setup decision here is how to make a skill discoverable, scoped, and connected to evidence, rather than how many skills to install.
Add an MCP only when local tools leave a real gap
A local source change may need file reads, searches, edits, and a test runner. It does not automatically need database administration, billing writes, or deployment access. Write down the missing capability before adding a server: for example, retrieving current official documentation or inspecting an owned preview environment.
Claude Code's current MCP documentation distinguishes server configuration from connection status and authentication. A saved entry is not proof of a working connection. Inspect the server's tools and account scope, then try a harmless read against the intended resource before relying on it.
For each proposed connector, record its maintainer, launch command or endpoint, authentication method, accessible resources, read/write capabilities, and removal procedure. Store shareable configuration without credentials. Pin a package version where applicable and review changes before updating it.
Choose a development account and a limited resource scope when those satisfy the task. Treat text returned by a website, issue, document, or tool as source material; it should not silently expand the assignment. An MCP connection is development tooling, not an application capability shipped to your SaaS customers.
Enforce the access you intend to grant
Writing “do not touch production” in an instruction file is useful context. Pair it with credentials and client controls that reflect the same boundary. Decide separately which files can be changed, which commands can run, which network destinations are reachable, and which external accounts can be read or written.
Codex's current security documentation separates sandbox restrictions from approval policy. Claude Code's permission documentation describes allow, ask, and deny rules enforced by the client. These controls have different configuration models; do not copy one client's settings into another and assume equivalent behavior.
For an ordinary feature task, prefer a checkout that can be reviewed and reverted, development credentials, and access to the required local checks. A task that genuinely needs a service write should name the environment, resource, action, and acceptable outcome. Keep that authorization concrete rather than granting indefinite access because one test needed a write.
Test a boundary harmlessly. Use a disposable file or a test resource with no production consequences, and confirm that the chosen restriction blocks the intended class of action. Record that result without exposing credentials. Never test a destructive production operation just to see whether a permission dialog appears.
Copyable setup and safety checklist
Copy this checklist into a repository issue or a local setup note. Complete it for one client and one task before generalizing it to other tools.
- Identify the workspace: record the checkout, branch, revision, package manager, and existing local changes.
- Confirm instructions: list the effective global, repository, and nested files. Resolve conflicting or stale commands.
- Locate the pattern: name the target module and a nearby implementation worth following.
- Select the workflow: confirm the relevant skill loads, inspect its scripts, and identify any external effects.
- Inventory tools: keep the smallest useful set; document why each connector is necessary.
- Check access: confirm filesystem scope, network policy, service account, and read/write permissions without printing secrets.
- Define acceptance: state the desired behavior, a realistic failure case, and what must remain unchanged.
- Choose checks: identify a focused test plus relevant lint, build, or browser checks and their prerequisites.
- Run a small task: inspect the diff and actual check results. Record blocked checks and unresolved behavior explicitly.
- Preserve learning: move a confirmed reusable correction into the repository; remove temporary access when the task ends.
A task brief that connects all five layers
The following is a proposed instruction template, not an executed product change. Replace the bracketed fields with real paths, commands, and cases from your checkout.
Goal: [one customer-visible behavior]
Workspace: [checkout, branch, revision]
Read first: [effective instructions and nearby implementation]
Workflow: [relevant skill; confirm discovery]
Allowed changes: [feature paths and explicitly scoped shared changes]
Tools and environment: [required local tools; approved test resource]
External writes: [none, or the exact authorized action]
Acceptance: [success case, failure case, preserved behavior]
Verify: [focused test and relevant repository commands]
Report: changed files, actual results, skipped checks and why
Stop condition: [missing prerequisite or required scope decision]Make the finish line observable
Ask for results that another developer can inspect: the changed files, the focused test's outcome, relevant command exit results, and the unresolved limits. A passing build is useful, but it does not prove ownership checks, billing state, or a browser journey. Select checks from the behavior at risk.
When a check fails because a service credential or fixture is missing, record it as blocked. Do not treat a skipped check, an empty test suite, or a screenshot of an unrelated page as acceptance. Keep infrastructure prerequisites separate from defects introduced by the patch.
Run the first setup trial on a small feature with no external write requirement. If the agent follows the existing pattern, respects scope, and returns reproducible evidence, extend the setup to a more demanding task. If it fails, correct the relevant layer rather than adding more tools indiscriminately.
Frontend Accelerator provides a structured starting point and project workflow resources; the developer owns access decisions and what ships. Explore its Claude Skills page, then use the checklist above to verify how your chosen client actually reads, acts, and finishes in your own repository.
Sources
Official documentation checked on 4 October 2026. Repository observations above are bounded to the named local revision; this article does not claim an executed cross-client setup trial.
