- Preface i
-
1 The Landscape --- Claude Code, Aider, Cursor, and Local Tools 2
- 1.1 The Shift From Chat Assistance to Agentic Development 3
- 1.2 A Taxonomy of AI Development Tools 4
- 1.3 Autocomplete Tools: Fast, Narrow, and Low-Friction 6
- 1.4 Chat-Based Coding Assistants: Useful but Disconnected 8
- 1.5 IDE-Integrated Agents: Convenient but Editor-Bound 9
- 1.6 Terminal-Based Coding Agents: The New Power Tool 10
- 1.7 Claude Code, Aider, Cursor, and Similar Tools: How to Think About Them 12
- 1.8 Local and Open-Weight Coding Models 13
- 1.9 Cloud Agents vs. Local Agents 15
- 1.10 Context Windows, Repository Maps, and Why Agents Get Lost 17
- 1.11 Terminal State, Command Execution, and Feedback Loops 18
- 1.12 The Real Productivity Pattern: Human Designs, Agent Executes 20
- 1.13 Choosing the Right Tool for the Job 21
- 1.14 A Practical Starter Stack 23
- 1.15 What This Book Will Teach You Next 25
-
2 Setup and Your First Session 27
- 2.1 Before You Install Anything 27
- 2.2 The Three Layers of Setup 28
- 2.3 Choosing a First Repository 30
- 2.4 Installing the Agent Without Making the Book Fragile 31
- 2.5 Credential and API Key Hygiene 32
- 2.6 Terminal Readiness 34
- 2.7 The Clean Git Baseline 35
- 2.8 Starting the First Session 36
- 2.9 Read-Only Repository Discovery 38
- 2.10 Verifying Tool Behavior 39
- 2.11 Running the First Safe Command 40
- 2.12 The First Tiny Change 41
- 2.13 Reading the Diff 42
- 2.14 Common First-Session Failures 43
- 2.15 Ending the Session Cleanly 45
- 2.16 What We Learned From the First Session 45
-
3 Context Files: CLAUDE.md and AGENTS.md 47
- 3.1 Why Agents Need Project Memory 47
- 3.2 The Three Instruction Layers 49
- 3.3 CLAUDE.md, AGENTS.md, and Tool-Specific Context 51
- 3.4 What Belongs in a Repository Context File 51
- 3.5 What Does Not Belong in a Context File 54
- 3.6 A Minimal Context File Template 55
- 3.7 A Full Production Context File Template 56
- 3.8 Stack-Specific Context Examples 57
- 3.9 Architecture Boundaries 58
- 3.10 Command Rules and Safety Levels 60
- 3.11 Files and Directories the Agent Should Avoid 61
- 3.12 Token Economy: Keeping Context Compact 62
- 3.13 Testing the Context File 63
- 3.14 Maintaining Context Files Over Time 64
- 3.15 Team Context vs. Personal Context 66
- 3.16 Hands-On Lab: Build a Context File for an Existing Repository 66
- 3.17 Common Mistakes 68
- 3.18 Chapter Summary 69
-
4 Permissions, Sandboxing, and Safety 72
- 4.1 Why Agent Safety Is Different From Normal Development Safety 72
- 4.2 The Safety Model: Guide, Limit, Verify, Recover 74
- 4.3 Threats and Failure Modes 75
- 4.4 Permission Boundaries 76
- 4.5 Command Risk Levels 78
- 4.6 Host Execution vs. Sandboxed Execution 79
- 4.7 The Minimal Practical Sandbox 80
- 4.8 Building a Basic Agent Sandbox 81
- 4.9 Mounting Repositories Safely 84
- 4.10 Environment Variables and Secrets in Sandboxes 86
- 4.11 Network Access 87
- 4.12 Approval Gates 88
- 4.13 Monitoring What the Agent Changed 89
- 4.14 Recovery Patterns 90
- 4.15 Hands-On Lab: Build and Use a Local Agent Sandbox 91
- 4.16 When Sandboxing Is Not Enough 93
- 4.17 Common Mistakes 94
- 4.18 Chapter Summary 95
-
5 Prompting for Code --- The Declarative Method 97
- 5.1 Why ``Prompt Engineering'' Is the Wrong Frame for Coding Agents 97
- 5.2 The Declarative Method 99
- 5.3 Vague Prompt vs. Declarative Prompt 101
- 5.4 Define the Goal Before the Implementation 103
- 5.5 Define the Scope 104
- 5.6 Files to Inspect, Modify, and Avoid 105
- 5.7 Constraints That Prevent Architectural Drift 106
- 5.8 Inputs and Expected Outputs 107
- 5.9 Verification Commands 108
- 5.10 Stopping Conditions 109
- 5.11 The Investigation-First Prompt 111
- 5.12 The Implementation Prompt 112
- 5.13 The Test-First Prompt 113
- 5.14 The Documentation Prompt 114
- 5.15 The Refactor Prompt 115
- 5.16 The Bug-Fix Prompt 116
- 5.17 Incremental Prompting 118
- 5.18 Prompt Libraries 119
- 5.19 Common Prompting Mistakes 120
- 5.20 Hands-On Lab: Turn a Vague Request Into a Work Order 121
- 5.21 Chapter Summary 125
-
6 Multi-File Refactoring and Navigation 126
- 6.1 Why Multi-File Work Is Different 126
- 6.2 Refactoring vs. Rewriting vs. Feature Work 127
- 6.3 The Navigation-First Principle 129
- 6.4 Repository Maps and Symbol Awareness 130
- 6.5 Search Patterns for Codebase Navigation 131
- 6.6 Identifying Dependency Chains 133
- 6.7 Planning the Refactor Sequence 135
- 6.8 Interface Changes and Ripple Effects 138
- 6.9 Layered Architecture Refactors 139
- 6.10 Keeping the Codebase Buildable 140
- 6.11 Batching Changes 141
- 6.12 Working With Tests During Refactors 142
- 6.13 Handling Generated Files, Lock Files, and Snapshots 143
- 6.14 Stopping Conditions for Multi-File Work 144
- 6.15 Worked Example: Replace a Hardcoded Service With an Interface 145
- 6.16 When to Let the Agent Continue vs. When to Take Over 147
- 6.17 Hands-On Lab: Controlled Multi-File Refactor 148
- 6.18 Common Mistakes 150
- 6.19 Chapter Summary 151
-
7 Reviewing Agent Output: Diffs and Audits 153
- 7.1 The Diff Is the Real Answer 153
- 7.2 First-Pass Review: What Changed? 155
- 7.3 Changed Files: Expected, Unexpected, and Suspicious 156
- 7.4 Mechanical vs. Semantic Changes 157
- 7.5 Scope Compliance 159
- 7.6 Architecture Review 160
- 7.7 Security Review 162
- 7.8 Test Review: Did the Agent Prove the Right Thing? 164
- 7.9 Hallucinated APIs and Invented Behavior 165
- 7.10 Dependency and Package Review 166
- 7.11 Configuration, Migration, and Infrastructure Review 168
- 7.12 Data and Behavior Review 169
- 7.13 Performance and Maintainability Review 170
- 7.14 Reviewing the Agent's Explanation 171
- 7.15 Using an Agent to Review Another Agent 173
- 7.16 Accept, Edit, Split, or Reject 174
- 7.17 Worked Example: Hidden Agent Errors in a Small Diff 176
- 7.18 Hands-On Lab: Audit an Agent-Generated Change 178
- 7.19 Common Review Mistakes 180
- 7.20 Chapter Summary 181
-
8 When to Delegate vs. Do It Yourself 183
- 8.1 The Delegation Trap 183
- 8.2 The Five Delegation Filters 184
- 8.3 The Delegation Spectrum 186
- 8.4 Highly Delegable Tasks 187
- 8.5 Collaborative Tasks 189
- 8.6 Human-Only First Tasks 190
- 8.7 The Review-Cost Equation 191
- 8.8 Task Ambiguity 192
- 8.9 Testability and Verification 193
- 8.10 Reversibility 194
- 8.11 Context Availability 195
- 8.12 Tool Choice by Task Type 196
- 8.13 Time, Token, and Attention Budgets 198
- 8.14 Skill Retention 199
- 8.15 Personal Delegation Rules 200
- 8.16 Team Delegation Rules 201
- 8.17 Worked Examples: Should I Delegate This? 202
- 8.18 Hands-On Lab: Build a Delegation Decision 203
- 8.19 Common Delegation Mistakes 205
- 8.20 Chapter Summary 206
-
9 Git Workflows with Agents: Branching and Micro-commits 208
- 9.1 Why Git Matters More With Agents 208
- 9.2 The Clean Baseline Rule 209
- 9.3 Branching for Agent Tasks 211
- 9.4 Micro-commits: The Atomic Checkpoint Pattern 212
- 9.5 Commit Boundaries for Agent Work 214
- 9.6 Keeping Human and Agent Work Separate 215
- 9.7 Staging Discipline 216
- 9.8 Writing Commit Messages From Diffs 218
- 9.9 Using Agents to Summarize Diffs Safely 220
- 9.10 The Agent Micro-commit Loop 221
- 9.11 Rollback and Recovery 222
- 9.12 Working With Generated Files and Lock Files 224
- 9.13 Pull Requests for Agent-Assisted Work 225
- 9.14 Agents and Merge Conflicts 226
- 9.15 Git Worktrees for Parallel Agent Sessions 227
- 9.16 Comparing Two Agent Approaches 228
- 9.17 Hands-On Lab: Agent Work as Micro-commits 229
- 9.18 Common Git Mistakes With Agents 231
- 9.19 Chapter Summary 233
-
10 Testing Agent-Written Code: The Auto-Repair Loop 235
- 10.1 Tests Are the Agent's Reality Check 235
- 10.2 Existing Tests Before New Code 236
- 10.3 Test-First, Test-During, and Test-After 237
- 10.4 What Makes a Good Agent-Written Test? 238
- 10.5 Targeted Test Commands 240
- 10.6 Feeding Failures Back to the Agent 242
- 10.7 The Manual Repair Loop 243
- 10.8 The Auto-Repair Loop 245
- 10.9 Building a Simple Test-Repair Script 246
- 10.10 Guardrails for Auto-Repair 248
- 10.11 Preventing Test Cheating 249
- 10.12 Coverage: Useful Signal, Not a Goal by Itself 251
- 10.13 Flaky Tests and Environment Failures 252
- 10.14 When Tests Are Missing 253
- 10.15 Testing Across Stacks 254
- 10.16 Worked Example: From Failing Test to Repair 254
- 10.17 Hands-On Lab: Build a Bounded Repair Loop 257
- 10.18 Common Testing Mistakes With Agents 259
- 10.19 Chapter Summary 260
-
11 Local vs. Cloud Trade-Offs 263
- 11.1 The False Choice: Local or Cloud 263
- 11.2 The Decision Dimensions 264
- 11.3 What Cloud Models Are Usually Better At 266
- 11.4 What Local Models Are Usually Better At 266
- 11.5 Data Privacy and Code Exposure 267
- 11.6 Cost and Token Economics Without Vendor Fragility 269
- 11.7 Latency, Throughput, and Developer Flow 271
- 11.8 Hardware Realities for Local Models 271
- 11.9 Model Quality and Benchmark Traps 273
- 11.10 Local Model Tooling 275
- 11.11 Cloud Agent Tooling 276
- 11.12 Hybrid Workflows 276
- 11.13 Policy and Compliance 278
- 11.14 Choosing a Setup by Task Type 279
- 11.15 Budget Controls and Usage Hygiene 280
- 11.16 When Local Is Not Worth It 281
- 11.17 When Cloud Is Not Appropriate 282
- 11.18 Hands-On Lab: Build a Local/Cloud Decision Matrix 283
- 11.19 Common Mistakes 285
- 11.20 Chapter Summary 286
-
12 Model Context Protocol (MCP) and Custom Tools 287
- 12.1 Why Coding Agents Need Tools 287
- 12.2 MCP in One Practical Picture 288
- 12.3 Tools vs. Shell Commands 289
- 12.4 Good Custom Tool Candidates 290
- 12.5 Bad Custom Tool Candidates 292
- 12.6 Designing a Tool Contract 292
- 12.7 Read-Only First 294
- 12.8 Data Boundaries and Sanitization 295
- 12.9 A Small Local Tool Server Example 296
- 12.10 Tool Registration Conceptually 299
- 12.11 Calling the Tool From an Agent Prompt 300
- 12.12 Tool Output Review 301
- 12.13 Tool Call Logging 302
- 12.14 Approval-Gated Tools 303
- 12.15 Tool Errors and Failure Modes 305
- 12.16 Security Review for Custom Tools 306
- 12.17 Local vs. Remote Tool Servers 308
- 12.18 Hands-On Lab: Build a Read-Only Project Inventory Tool 309
- 12.19 Common Mistakes 311
- 12.20 Chapter Summary 312
-
13 Team Patterns and Shared Guidelines 314
- 13.1 Why Team AI Adoption Fails 314
- 13.2 The Team Operating Model 316
- 13.3 Approved, Restricted, and Forbidden Uses 317
- 13.4 Shared Context Files Across Repositories 319
- 13.5 Prompt Libraries as Team Assets 320
- 13.6 Shared Sandboxes and Development Environments 322
- 13.7 Shared Custom Tools and MCP Servers 323
- 13.8 Review Expectations for Agent-Assisted Changes 325
- 13.9 Disclosure and Traceability 326
- 13.10 Junior Developers and Learning 327
- 13.11 Senior Developers and Tech Leads 329
- 13.12 Cost and Usage Visibility 330
- 13.13 Security and Data Handling Rules 331
- 13.14 Team Prompt and Context Reviews 332
- 13.15 Handling Disagreements About Agent Use 334
- 13.16 Team Metrics That Actually Help 334
- 13.17 Hands-On Lab: Create a Team AI Usage Guide 335
- 13.18 Common Mistakes 338
- 13.19 Chapter Summary 339
-
14 Continuous Integration and Agent Automation 341
- 14.1 Why Put Agents in CI? 341
- 14.2 Automation Levels 342
- 14.3 The Safe CI Agent Pattern 343
- 14.4 Permissions and Secrets in CI 344
- 14.5 Runtime, Cost, and Loop Limits 347
- 14.6 Report-Only Failure Analysis 348
- 14.7 Patch Artifact Pattern 350
- 14.8 Lint and Formatting Triage 352
- 14.9 Test Failure Triage 353
- 14.10 Dependency and Vulnerability Review 354
- 14.11 Pull Request Summary Assistance 355
- 14.12 CI Configuration Examples 357
- 14.13 Handling Untrusted Contributions 361
- 14.14 Prompt Injection in CI Logs and Files 363
- 14.15 Approval Gates 364
- 14.16 Observability and Audit Trails 364
- 14.17 Hands-On Lab: Add a Report-Only Agent CI Job 365
- 14.18 Common Mistakes 368
- 14.19 Chapter Summary 369
-
15 Pitfalls, Anti-Patterns, and Maintenance 370
- 15.1 The Honeymoon Phase 370
- 15.2 Anti-Pattern: Prompting Instead of Thinking 371
- 15.3 Anti-Pattern: Accepting Code You Cannot Explain 373
- 15.4 Anti-Pattern: Context Rot 374
- 15.5 Anti-Pattern: Prompt Library Rot 376
- 15.6 Anti-Pattern: Test Theater 377
- 15.7 Anti-Pattern: Review Theater 379
- 15.8 Anti-Pattern: Automation Without Ownership 380
- 15.9 Anti-Pattern: Tool Sprawl 381
- 15.10 Anti-Pattern: Invisible Cost Drift 382
- 15.11 Anti-Pattern: Privacy Normalization 384
- 15.12 Anti-Pattern: Skill Decay 385
- 15.13 Anti-Pattern: Managerial Velocity Fantasy 387
- 15.14 Maintenance Rhythm 388
- 15.15 Workflow Health Checks 390
- 15.16 When to Stop the Agent 392
- 15.17 Recovery After a Bad Agent Session 393
- 15.18 Hands-On Lab: Build Your AI Maintenance Plan 394
- 15.19 The Sustainable AI-Assisted Developer 397
- 15.20 Chapter Summary 397
AI-Assisted Development
Working With Coding Agents
A working engineer's guide to building and maintaining production software with autonomous terminal coding agents (410 manuscript pages).
Minimum price
$19.99
$29.99
You pay
Author earns
PDF
About
About the Book
AI-Assisted Development is a practical, opinionated guide for working software engineers who want to build and maintain production software in partnership with autonomous terminal coding agents (Claude Code, Aider, and other CLI assistants). It teaches the disciplined methodology the hype skips: tool selection, secure setup, context files, sandboxing and permissions, declarative prompting, multi-file refactoring, diff auditing, delegation strategy, git micro-commit workflows, automated test-repair loops, local-versus-cloud trade-offs, extending agents with the Model Context Protocol, team patterns, CI/CD agent automation, and long-term maintenance and anti-patterns.
Categories
Feedback
Author
About the Author
Yohan Rodriguez
Yohan is a Senior Full-Stack Software Engineer with extensive experience delivering scalable, end-to-end software solutions across web, enterprise, and cloud-based environments. He specializes in architecting robust platforms, modernizing legacy systems, driving cloud transformation efforts, and building integration-heavy applications that support critical business workflows. He is recognized for translating complex requirements into reliable, maintainable, and high-value solutions across industries such as insurance, cybersecurity, and professional services.
Known for combining strong technical execution with a practical business mindset, he has contributed to projects from concept and design through production delivery and long-term support. His experience includes collaborating with cross-functional teams, improving development workflows, solving complex technical challenges, and helping organizations deliver dependable software products that adapt to changing business needs. He brings a balanced approach to engineering that values quality, efficiency, and continuous improvement.
Contents
Table of Contents
Get the free sample chapters
Click the buttons to get the free sample in PDF or EPUB, or read the sample online here
The Leanpub 60 Day 100% Happiness Guarantee
Within 60 days of purchase you can get a 100% refund on any Leanpub purchase, in two clicks.
See full terms...
Earn $8 on a $10 Purchase, and $16 on a $20 Purchase
We pay 80% royalties on purchases of $7.99 or more, and 80% royalties minus a 50 cent flat fee on purchases between $0.99 and $7.98. You earn $8 on a $10 sale, and $16 on a $20 sale. So, if we sell 5000 non-refunded copies of your book for $20, you'll earn $80,000.
(Yes, some authors have already earned much more than that on Leanpub.)
In fact, authors have earned over $15 million writing, publishing and selling on Leanpub.
Learn more about writing on Leanpub
Free Updates. DRM Free.
If you buy a Leanpub book, you get free updates for as long as the author updates the book! Many authors use Leanpub to publish their books in-progress, while they are writing them. All readers get free updates, regardless of when they bought the book or how much they paid (including free).
Most Leanpub books are available in PDF (for computers) and EPUB (for phones, tablets and Kindle). The formats that a book includes are shown at the top right corner of this page.
Finally, Leanpub books don't have any DRM copy-protection nonsense, so you can easily read them on any supported device.
Learn more about Leanpub's ebook formats and where to read them
Write and Publish on Leanpub
You can use Leanpub to easily write, publish and sell in-progress and completed ebooks and online courses!
Leanpub is a powerful platform for serious authors, combining a simple, elegant writing and publishing workflow with a store focused on selling in-progress ebooks.
Leanpub is a magical typewriter for authors: just write in plain text, and to publish your ebook, just click a button. (Or, if you are producing your ebook your own way, you can even upload your own PDF and/or EPUB files and then publish with one click!) It really is that easy.