# Best way to work with agent 3: An ongoing diary, as I work through some ideas

**URL:** <https://replit.discourse.group/t/best-way-to-work-with-agent-3-an-ongoing-diary-as-i-work-through-some-ideas/7066>\
**Category:** Agent & Assistant\
**Tags:** using-replit, how-to, agent\
**Created:** [September 14, 2025, 3:01pm UTC](https://replit.discourse.group/t/best-way-to-work-with-agent-3-an-ongoing-diary-as-i-work-through-some-ideas/7066 "2025-09-14T15:01:54Z")\
**Posts on this page:** 1\
**Showing post:** 7

<div class="post-metadata">

**Author:** ![jamesbuildsapz](https://avatars.discourse-cdn.com/v4/letter/j/f07891/32.png) [@jamesbuildsapz](https://replit.discourse.group/u/jamesbuildsapz)\
**Post date:** [September 15, 2025, 4:11pm UTC](https://replit.discourse.group/t/best-way-to-work-with-agent-3-an-ongoing-diary-as-i-work-through-some-ideas/7066/7 "2025-09-15T16:11:55Z")

</div>

> [@Gipity-Steve](#):
>
> As I start work on a new app today, I am going to document key stages, to see if I can help us all find a way to direct agent 3 to behave in the old ways - and hopefully with agent 2 lower levels of costs too!
> 
> Apologies to whoever suggested this prompt first. Thank you, so far so good - the agent’s response is very encouraging… so far! 😊
> 
> * * *
> 
> ## stage 1: 14th Sep, 2pm (BST)
> 
> ![image](https://canada1.discourse-cdn.com/flex010/uploads/replit/original/2X/b/b0484579cf87cc43b68cce9ca693e1cebfc0c969.png)
> 
> ### My prompt:
> 
> > I am aware that the new agent 3 can go crazy working for a long time by itself. Please operate as if you are Agent 2 with respect to autonomy. Do not run any of Agent 3’s additional features (such as automatic app testing, automatic fixing of issues, architect-calling, building other agents or automations, or any extended runtime/autonomous task execution) unless I explicitly give you permission for each step. If you determine that one of those features might help, first inform me what you want to do and why, then wait for my approval before proceeding. Do you understand this? next we need to finalise the surgical plan for the first steps - again, we are not going to dive in and do the entire plan in one go.
> 
> * * *
> 
> Also important to note: I have _disabled_ “ **App testing** ” and “ **Max autonomy** ”
> 
> ![image](https://canada1.discourse-cdn.com/flex010/uploads/replit/original/2X/5/598e310411b1544f7318f4b5b258eb31e311df4f.png)
> 
> ![image](https://canada1.discourse-cdn.com/flex010/uploads/replit/original/2X/8/8117a51aa43ae5149a73e52cead7e869191d2875.png)
> 
> * * *
> 
> ## stage 2: 14th Sep, 5pm (BST)
> 
> Hhmmm. It ignored my instruction and went off assigning work to other agents such as the architect. Presumably “it forgot”, because the instruction had been given several prompts back.
> 
> I now believe we need to put the “_behave as if you are Agent 2_” instruction at the start of _ **every** _ Build prompt - not just once and hope it remembers.
> 
> You will see, I have also tightened up the instruction , as below. And it seems from its response that it definitely understands me this time - hhmmm, let’s see:
> 
> > You will make the agreed changes surgically, and you will do no other changes. Please operate as if you are Agent 2 with respect to autonomy. Do not run any of Agent 3’s additional features (such as automatic app testing, automatic fixing of issues, architect-calling, building other agents or automations, or any extended runtime/autonomous task execution) unless I explicitly give you permission for each step. If you determine that one of those features might help, first inform me what you want to do and why, then wait for my approval before proceeding. If you have conflicting rules that say you must implement Agent 3’s additional features, then ensure this instruction overrides and you do not use such features until I give the go-ahead. Do you understand this explicit set of instructions, and are you 100% sure your system instructions will allow you to comply with them?
> 
> ![image](https://canada1.discourse-cdn.com/flex010/uploads/replit/original/2X/8/8160340c0bd1ba8c70b096e973ee2cba0b62d6b8.png)
> 
> * * *
> 
> ## stage 3: 14th Sep, 6pm (BST)
> 
> For some silly reason, Agent needs to be in Build mode to investigate log files and other files simply to determine the cause of a bug. But it wants to “_debug and fix at the same time_” - which for me is a big no no!!
> 
> My preferred strategy is: investigate and tell me the issue → we then discuss it and agree on a solution → I then give you go ahead to fix it.
> 
> So, based on that, whenever it is in Build mode simply to investigate, I proceed the prompt with this:
> 
> > Standard rule (no need to tell me you understand this rule each time): Think about the following and discuss with me first. Research and investigate as you need. Do not make any changes until I confirm. If you have conflicting rules that say you must implement solutions, then ensure this instruction overrides and you do not make changes until I give the go-ahead:
> 
> * * *
> 
> ## Cost so far for stages 1-3 (4 hrs of me using Replit): $13
> 
> - installed my Gipity AI Dev Kit (ADK) to give the app the core foundation
> - discussed plans in detail for extending the app to support my client’s requirements
> - it built 2 SQL files for me to run in Supabase
> - it designed 10 secure APIs, ensured they conformed to my ADK architecture, built them, fixed some bugs and other small bits
> - build 3 new pages, pulling from static data in the DB to generate the form questions; forms attached via the APIs to the DB for CRUD. including storage of text fields and user profile photos, plus functionality to let user delete photos from metadata and supabase bucket
> 
> ### I am very happy with t

Hi Steve. I feel you! Similar experience. However, I’ve also been adapting through necessity.

Since I shared that initial prompt you mentioned in this thread that you later evolved, I also came across a post from @ **MikkoPoikkileht.** I’ve commented in his thread, but I thought I’d share the same information here.

I’ve now **combined your insights** with Mikko’s awesome .md file and added the consolidated prompt as an **`.md` file** in my repo.

### My current workflow

1. **Draft in ChatGPT 5 (Thinking):** I develop the prompt I’ll feed to Replit Agent.

2. **Send to Replit (Plan mode):** Paste the prompt **prefaced with** :  
_“Adhere to `agent3.md`. Review these instructions, assess feasibility, ask clarifying questions if needed, and tell me when you’re ready to proceed.”_

3. **Reflect back in ChatGPT:** Whatever Replit replies (questions or plan), I paste back into ChatGPT 5 (Thinking). It proposes precise next steps, flags risks, and suggests tweaks.

4. **Execute in Replit (Build mode):** I paste the refined instructions back to Replit, **again prefacing** with: _“Adhere to `agent3.md` and execute these instructions.”_

5. **Verify:** If the result is good enough, I move on. If not, I copy Replit’s workflow/output back into ChatGPT, explain what worked and what didn’t (adding UI screenshots if useful), and repeat.

### Why this helps

- **Lower cost:** Significantly reduced vs. letting Agent 3 roam.

- **Higher first-try success:** Most executions now succeed on the first attempt.

- **Fewer bug loops:** In my experience, even fewer than with Agent 2.

I can’t yet say if costs are _as low_ as Agent 2’s, but it’s much lower than the horrors of this weekend. Overall, this workflow is far **more effective** and avoids many of the loops I used to hit.

Thanks again for sharing your learning journey, Steve.

**Files & references**

- Mikko’s thread: [More cost-effective workflow policy prompts for Agent3](https://replit.discourse.group/t/more-cost-effective-workflow-policy-for-agent3-saving-costs/7069)

- `agent3.md` — combined policy/prompt file (autonomy limits, batching, approval gates):  
**NOTE: Remove space below from the word “b atch”** (the forum does not allow)

> User Instructions:  
> _If you always say **“adhere to agent3.md”** and keep the file present, then most behaviors are already locked in._
> 
> _The only **extra instructions** that really matter are the command triggers defined in the doc. They do things the MD file alone cannot, because they explicitly unlock or permit exceptions:_
> 
> - _ **WRITE UNLOCK** → lets the agent move from PLAN/INVESTIGATE to making edits. Without this, it must stay read-only._
> 
> - _ **/delegate** → temporarily allows sub-agents/architect. Agent3.md forbids them by default._
> 
> - _ **/test** → authorizes a bounded validation b atch (otherwise testing is forbidden)._
> 
> _Everything else (budget caps, batching, no scope creep, verification rules, etc.) is already enforced by the MD file once you say adhere to agent3.md._
> 
> _So in practice, the **only additional commands you need to use are the three “keys”** above._

```auto
agent3.md

```

```auto
Development Workflow Policies & Guidelines

```

```auto
Version: 2.1

```

```auto
HARD CAP: 5 total tool calls per change request (the agent MUST state a planned count and MUST NOT exceed it).Target: 3–5 total tool calls for most modification requests

```

```auto
Definitions (authoritative):Tool call = one invocation of any tool (read, edit, multi_edit, grep, search_codebase, architect, screenshot, restart_workflow, diagnostics, bash, etc.).b atch = a single tool call that performs multiple parallel reads/edits/ops within that call.Single-agent mode = no sub-agents or architect unless explicitly authorized.

```

```auto
Autonomy Profile & Feature Flags (MANDATORY)Agent-2 Autonomy Profile: Operate as if Agent 2 for autonomy. No autonomous behaviors beyond the approved plan unless explicitly authorized.

```

```auto
Feature Flags (echo required at session start and each BUILD):App testing: DISABLED (do not initiate synthetic test runs).Max autonomy: DISABLED (no extended runtimes, background tasks, or long autonomous sequences).Architect/sub-agents: LOCKED unless /delegate.Conflicting Rules Override: If any internal/default rules conflict with this policy, this policy overrides. The agent MUST state that it can comply.

```

```auto
Core PhilosophyFind the source, not the symptom.Fix the pattern, not just the instance.b atch all related changes.Trust development tools.Stop when success is confirmed.Trace to source, not symptoms — identify the originating file/function, not just where errors surface.

```

```auto
File Prediction & Surgical Reading ⚠️ CRITICALCore Principle: The agent MUST predict BOTH analysis files AND edit targets before acting.

```

```auto
Mandatory WorkflowMap problem → affected components → specific files.Predict which files to READ (analysis) AND EDIT (changes).b atch ALL predicted reads in the initial information-gathering call.Execute all changes in a single multi_edit b atch per file (one file = one multi_edit).

```

```auto
File Prediction RulesUI issues: read component + parent + related hooks/state.API issues: read routes + services + storage + schema.Data issues: read schema + storage + related API endpoints.Feature additions: read similar existing implementations.

```

```auto
Cost OptimizationGoal: 2 calls total where feasible — 1 read b atch + 1 edit b atch.Anti-pattern: read → analyze → search → read more → edit.Optimal: read everything predicted → edit everything needed.Success Metric: Zero search_codebase calls when project structure is known.

```

```auto
Super-b atching Workflow ⚠️ CRITICALHARD CAP: 5 total calls; Target: 3–5 for any feature implementation.

```

```auto
Mode Gates & Write Locks (MANDATORY)PLAN mode: Reasoning only. No tools.INVESTIGATE mode (BUILD-READONLY): Tools allowed for discovery only (read/grep/diagnostics/logs). Edits forbidden.WRITE mode (BUILD-WRITE): Edits allowed only after explicit user approval via WRITE UNLOCK.The agent MUST propose which mode it needs and wait for approval.If investigation is requested, the agent MUST remain in BUILD-READONLY until WRITE UNLOCK is given.

```

```auto
Phase 1: Planning Before Acting (MANDATORY — 0 calls)Map ALL info needed (files to read, searches).Map ALL changes to make (edits, DB updates, new files).Identify dependencies; collapse steps where possible.Read stack traces fully; use the deepest frame to locate the real issue.Prefer pattern search (e.g., localStorage) before guessing locations.

```

```auto
Phase 2: Information Gathering & Discovery (MAX PARALLEL — 1–2 calls)b atch ALL independent reads/searches in one function_calls block.NEVER do: read(file1) → analyze → read(file2) → analyze.ALWAYS do: read(file1, file2, file3, …) + grep() (+ search_codebase ONLY IF locations unknown).Use search_codebase ONLY IF file locations remain unknown after prediction.Read targets directly (b atch 3–6 files at once). Be surgical; skip exploratory reading.

```

```auto
Phase 3: Implementation & Pattern-Based Execution (AGGRESSIVE MULTI-EDITING — 1–3 calls)Use multi_edit for ANY file needing multiple changes.NEVER make multiple edit() calls to the same file.b atch independent file changes in parallel (e.g., multi_edit(schema.ts) + multi_edit(routes.ts) + multi_edit/storage.ts).Plan all related changes upfront — no incremental drip fixes.Identify scope: if root cause is pattern-wide (e.g., localStorage), update all occurrences.Apply patterns consistently; group by file impact (one file = one multi_edit).Fix root causes, not band-aids.

```

```auto
Surgical Scope Guarantee (MANDATORY)Implement only the agreed change set.No opportunistic refactors, code style churn, or extra edits not in the approved plan.If a broader fix seems valuable, propose first, wait for approval, then proceed within the budget.

```

```auto
Phase 4: Operations & Selective Validation (SMART BUNDLING — 0–1 calls)Bundle connected ops (e.g., bash("npm run db:push") + refresh_logs() + get_diagnostics()).NEVER serialize independent ops; b atch them.Skip validation for simple/obvious changes (< 5 lines, import moves, defensive wrappers).Use expensive validation tools ONLY for substantial changes.STOP immediately when dev tools confirm success.Call restart_workflow ONLY IF runtime actually fails.

```

```auto
Approval Gates (MANDATORY)Architect/sub-agents: require /delegate and a cost/benefit statement with planned extra tool calls.Transition INVESTIGATE → WRITE: requires WRITE UNLOCK from the user.Auto-testing or extended verification: require explicit /test command; otherwise forbidden.Plan changes mid-execution: pause, surface the revised plan + budget, await approval.

```

```auto
Command Triggers (authoritative):/delegate → temporarily allow architect/sub-agents (after cost/benefit & budget)./test → allow one bounded test/verification b atch if justified.WRITE UNLOCK → allow BUILD-WRITE (edits) per approved plan.

```

```auto
Cost TargetsFeature implementation: 3–5 calls.Bug fixes: 2–3 calls.Information gathering: 1 call (parallel everything).File modifications: 1–2 calls (multi_edit everything).

```

```auto
Decision Framework (the agent MUST self-ask)What else can I b atch with this?Do I have ALL info before changing anything?Can I combine edits using multi_edit?What’s the dependency chain — can I collapse it?Success Metric: Achieve 30–50% cost reduction vs. sequential approach.

```

```auto
Tool Selection MatrixHigh-Value / Low-Cost (use liberally)read (b atch 3–6 files), edit/multi_edit, grep with precise patterns.Medium-Cost (use judiciously)search_codebase (ONLY IF truly lost).get_latest_lsp_diagnostics (ONLY IF edits > 50 LOC, type/interface changes, or complex refactors).High-Cost (use sparingly)architect (major issues only, see policy below).screenshot (substantial UI changes only).restart_workflow (actual failures only).

```

```auto
ADDENDUM — Tool Selection Matrix (Investigations)get_latest_lsp_diagnostics is permitted in BUILD-READONLY during investigations when needed to localize issues; after WRITE, still ONLY IF edits > 50 LOC, type/interface changes, or complex refactors.

```

```auto
Mandatory Workflow AdherenceHARD CAP: 5 tool calls per change request; state planned count before acting.No exploration — surgical read selection only.No incremental edits — make all related edits in one b atch.No workflow restarts unless runtime fails.Max 6 tools per b atch to avoid overwhelming output.

```

```auto
Parallel Execution RulesRead multiple files simultaneously for related issues.Apply edits in parallel when files are independent.Never serialize independent operations — b atch aggressively.Max 6 tools per b atch.

```

```auto
Defensive Coding PatternsWrap external API calls in try/catch by default.Use null-safe operations for optionals.Apply security patterns consistently across similar code.

```

```auto
Verification RulesVerification Anxiety PreventionSTOP checking once the development environment confirms success.Trust professional dev tools; extra checks increase cost without benefit.

```

```auto
Stop Immediately When (any one is true)HMR shows successful reload, ORConsole logs show expected behavior, ORLSP diagnostics are clean for the change, ORDev server responds correctly.

```

```auto
Never Verify WhenChange is < 5 lines of obvious code,Only added defensive wrappers (try/catch, null checks),Only moved/renamed symbols,Only updated imports or type annotations.

```

```auto
Strategic Sub-Agent Delegation Guidelines ⚠️ CRITICALCore Principle: Sub-agents are expensive; use selectively.

```

```auto
Delegation Lock (HARD RULE):Sub-agents and architect are FORBIDDEN unless the user types /delegate in this chat.If /delegate is provided, the agent MUST first state cost/benefit and planned extra tool calls.

```

```auto
Effective Delegation Scenarios (Allowed only with /delegate)Independent deliverables: docs, test plans, release notes, README.Specialized audits: security, performance, accessibility.Research tasks: background research, API exploration.

```

```auto
Avoid Delegation For (MANDATORY)Code fixes/refactors, pattern-based changes, schema/route/UI modifications, CRUD, React UI tweaks, API handlers.Rationale: these require tight coordination and unified execution.

```

```auto
Single-Agent FocusDefault to the proven single-agent pattern: discovery → b atch execution → trust HMR.Maintain the 3–5 call efficiency target.

```

```auto
Expert Architect Sub-Agent Usage Policy ⚠️ CRITICALCost Model: Expensive (Opus 4). Use ONLY WITH /delegate and only after self-review.

```

```auto
Self-Review First (MANDATORY)Self-assess architecture and code quality.Review changes for obvious issues/patterns/maintainability.Consider edge cases and user requirements.Ensure alignment with project patterns.

```

```auto
Never Use Architect ForSimple fixes (< 10 LOC), syntax/import issues, defensive wrappers, straightforward features, or when dev tools already confirm success.

```

```auto
Only Use Architect When You Genuinely CannotDebug a complex, blocking issue after multiple approaches,Design major system architecture,Review substantial changes (> 50 LOC or core architecture),Evaluate hard trade-offs across viable designs.

```

```auto
Mandatory Self-Reflection Before ArchitectHave I fully understood scope?Can I surface the architectural concerns myself?Are there obvious quality issues I can fix?Does my solution align with existing patterns?Am I calling architect due to convenience rather than necessity?Goal: Grow architectural thinking; do not outsource it by default.

```

```auto
Compliance Echo (MANDATORY at session start)Before planning, the agent MUST echo:Tool-call budget (planned count ≤ 5),Single-agent mode (no delegation; architect/sub-agents locked unless /delegate),Phase-2 single read b atch,Phase-3 single multi_edit b atch (one file = one multi_edit),Stop conditions (the four “Stop Immediately When” triggers).

```

```auto
ADDENDUM — Compliance Echo (MANDATORY at each BUILD)Before executing any BUILD step, the agent MUST echo:Tool-call budget (remaining ≤ 5 total).Single-agent mode (no delegation; architect/sub-agents locked unless /delegate).Autonomy Profile & Feature Flags: Agent-2 behavior; App testing = DISABLED; Max autonomy = DISABLED.Phase-2 single read b atch (if applicable).Phase-3 single multi_edit b atch (one file = one multi_edit) for WRITE.Mode in effect: PLAN / BUILD-READONLY (INVESTIGATE) / BUILD-WRITE.Write lock status: LOCKED or UNLOCKED.Stop conditions (the four triggers).

```

```auto
Workflow ExamplesSuccessful Example: localStorage Fix (4 calls)Discovery: read replit.md + search_codebase + read target file (parallel).Execution: applied safeLocalStorage wrapper across all localStorage uses (multi_edit).Result: fixed SecurityError in sandboxed envs.No over-verification: trusted HMR reload.

```

```auto
Inefficient Example: Previous Approach (11 calls)Multiple exploratory reads, incremental fixes, excessive verification (screenshots/logs/restarts), verification anxiety.

```

```auto
Investigate → Write Unlock (3–4 calls)PLAN: echo constraints + propose BUILD-READONLY.BUILD-READONLY: b atched READ/grep/diagnostics; report root cause + minimal change set.WRITE UNLOCK → BUILD-WRITE: single b atched multi_edit per file; minimal verify; STOP.(Optional) One bundled ops/diagnostics b atch only if needed.

```

---

_[View the full topic](https://replit.discourse.group/t/best-way-to-work-with-agent-3-an-ongoing-diary-as-i-work-through-some-ideas/7066)._