Mastering Claude Code

Mistake 1: Not Explaining Your Goal Clearly Enough

"I need a LinkedIn lead scraper."

Throw this single sentence at Claude Code and watch what happens. The agent cannot tell what industry of leads you want. It does not know which job titles to target. It ends up collecting random profiles. You waste time and model tokens, and you are left with a useless Excel file.

Recall when we scraped 622 job postings in the previous chapter. In plan mode, we provided the URL, told the agent how many pages there were, and described the fields we wanted. Claude Code came back with specific questions: Should we scrape individual detail pages, where should we save the data, are there filter conditions? Only after answering these questions did the agent establish an execution plan.

The Cascade Effect of Ambiguity

When your goal is ambiguous, every single judgment call the agent makes becomes uncertain. If you only say "lead scraper," the agent must make these decisions on its own.

A single wrong judgment about any of these questions throws off your entire result. The agent can ask clarifying questions, but only if you provided sufficient context in plan mode. In bypass permission mode with vague instructions, the agent guesses and proceeds on its own.

The Formula for Clear Goal Setting

Good goal setting follows a pattern.

Vague request:

Clear request:

You see the difference. The latter includes target (tech company CEOs), quantity (75 people), required data (name, company, email, profile link), output format (spreadsheet), and completion criteria (reaching 75).

[Figure 18-1] Comparison of Results: Vague Request vs. Clear Request

Treat the Agent as a Professional

A crucial shift in perspective is needed here. The agent is not a tool that mechanically follows instructions. It is a professional. You play the role of manager, delegating technical details to the agent.

Imagine hiring a real software developer to build an app. If you only say "Build me an app," the developer is stuck. They need information about what features are needed, who will use it, when the deadline is. The agent works the same way.

You do not need to know every technical detail. Ask "I want this result, what approach would work best?" and the agent uses a reasoning model like Opus 4.5 to compare five approaches and pick the optimal one.

Mistake 2: Not Defining What "Done" Means

If the first mistake is about "what," the second is about "when to stop."

Without a clear stopping point for the agent, three problems emerge: over-complication, needless repetition, endless research. If the agent thinks it can produce a better result, it keeps trying. This is both a strength and a weakness.

The Danger of Endless Loops

Look back at the dentist lead scraping case. We only asked to "find dentists in the U.S. and collect their contact information." What if the agent, after collecting 120 records, decides "we could gather more"? It might add new cities, explore new data sources, and keep refining the scraping tools without stopping.

The context gets exhausted, token costs balloon, and you never get the result you wanted.

Designing Completion Criteria

Completion criteria work on two axes: quantitative metrics and qualitative standards.

Examples of quantitative metrics:

Examples of qualitative standards:

We saw this principle work in the European sales lead scraping case. We set a goal of "500 records," and when the agent found only 52 in Europe, it spontaneously presented options. That happened because the completion criteria were clear. The agent itself recognized the gap between the goal and current status.

[Figure 18-2] Comparison of Execution Paths: Workflows with vs. without Completion Criteria

Co-Creating a Project Requirements Document with Your Agent

The solution to both mistakes converges on one practice: co-authoring a Project Requirements Document with your agent.

The Actual Process of Co-Authoring a Requirements Document

Switch on plan mode. Then say this.

The agent receiving this request goes through three stages.

Stage 1: Brainstorming and Research. Based on your stated goal, the agent investigates relevant APIs, MCP servers, and data sources. It may perform web searches. When we designed the YouTube analytics workflow, the agent compared YouTube Data API against MCP servers,that was this stage.

Stage 2: Questions and Answers. The agent asks multiple questions at once: "Which channels will we track?", "How often do you want reports?", "Should data also go into a sheet?", "Which email address should reports go to?" These questions fill in the blanks of the requirements document.

Stage 3: Planning. Once questions and answers are complete, the agent presents a comprehensive execution plan. It covers the goal, workflow structure, required tools, inputs, outputs, and edge case handling.

The Structure of a Workflow Document

When you look at a finished workflow document, its structure is itself the requirements document.

Because this document exists, when you run the same workflow next time, the agent produces consistent results. Without it, the agent approaches things differently each time, and output quality becomes uneven.

[Figure 18-3] A Real Example of a Workflow Document Based on Requirements

Three Benefits of Agent Workflows: Automatic Debugging, Voice-Based Control, Self-Learning

Now that we've covered how to avoid mistakes, let's examine three ways agent workflows are fundamentally different from traditional automation approaches.

Automatic Debugging: You No Longer Need to Read Logs

This was the daily reality of traditional workflow automation. You built something, ran it, and the system halted on an unforeseen edge case. Then you opened logs, analyzed error messages, and traced execution data one piece at a time to find the cause. Hours evaporated.

In agent workflows, this process is automated. You remember from the previous chapter when the dental lead web scraping tool extracted only two records. The agent self-diagnosed that "there's a problem with the parsing pattern," corrected the regular expression, updated the tool file, and ran it again. All of this happened without human intervention.

This is self-healing. Practically speaking, this matters greatly. While the agent builds workflows on your right monitor, you can work on something else on your left. You simply check in occasionally and keep it on track. Because AI is non-deterministic, it can veer off course, but it recovers from most errors on its own.

Voice-Based Control: You Don't Need to Learn Nodes

With tools like n8n, you had to learn what each node does, when to use it, and what parameters and settings mean. To connect to an API, you read documentation, found endpoints, configured JSON structure correctly, and figured out authentication. The barrier to entry was high.

In agent workflows, you describe what you want in natural language. The agent reviews available tools, checks for MCP connection servers, and researches API documentation if needed. A single sentence like "Please scrape European sales positions" encompasses tool selection, filter logic implementation, and Excel output format decisions.

The difference is summarized in the table below.

[Figure 18-4: Workflow Comparison Diagram of Traditional Automation and Agent Workflows]

Self-Learning: It Improves with Use

In the past, updating automation required manually modifying nodes and reconfiguring them. In agent workflows, the agent learns whenever it encounters a problem and updates both the workflow and tools.

Looking back at the job scraping workflow's progression, this quality becomes clear. In the first run, we successfully collected 209 records. In the second run, we reused the tool we had built. In the third run (dental leads), we created an entirely new tool but applied scraping patterns learned from earlier experience. Each workflow file and tool file grows more refined with each execution.

The Difference Between Manual Triggers and Scheduled Triggers

One important distinction needs to be made. Sitting in front of Claude Code and saying "Please do this task" is a manual trigger. In this case, the agent performs self-healing and learns in real time.

But when you deploy to run automatically every Monday at 6 AM, the situation changes. What gets deployed is the workflow and tools. The agent itself does not get deployed. So if the deployed workflow encounters an error during execution, it cannot fix itself. The agent is not there with it.

This is a current limitation of agent workflows. To improve a workflow operating on scheduled triggers, you must return to Claude Code, revise the workflow, and redeploy the updated version.

We've examined how to design robust workflows and the benefits that an agentic approach brings. When you clarify goals, define completion criteria, and draft requirements documents alongside the agent, workflow quality leaps forward. Now it's time to take these principles and learn how to connect powerful tool ecosystems provided by Google to your agent.

Kyung-Jin Kim, AI Expert Attorney

Specialist in AI Policy and Law, Former Member of National Assembly, Author of Multiple Books

If this book has stayed with you even for a moment, please support the next story coming into the world.

(Voluntary support account: Nonghyup Bank 302-1096-0948-81, Account holder: Kyung-Jin Kim)