AI Coding Agents: 10 Common Pitfalls and How to Avoid Them

Over the past while, I ran a call for feedback in a technical community asking, “What problems have you hit while using AI coding tools?” and received nearly two hundred responses. After sorting through them, I found that the confusions that keep recurring are highly concentrated: how to write the project spec file, why tokens are consumed so quickly, what the Model Context Protocol actually is, whether generated code should be reviewed, and how sensitive information is protected. Each question looks simple on its own, but combined together, they often determine whether a team can actually use these tools well.

Rather than replying piecemeal in the comments, it’s better to break the high-frequency questions down all at once. The ten questions below cover almost all the typical pitfalls I’ve seen.

1. What exactly is a project spec file, and can I skip writing one?

This is the question I’m asked most. The short answer: a project spec file is your project’s “team charter” — or, put another way, the “onboarding manual” you prepare for the agent.

AI coding tools read this file automatically at startup and treat the rules you write down as shared team conventions. You can of course skip it, but the result is like hiring a highly capable new colleague who knows nothing about your project background — every conversation has to start from scratch, re-explaining “what tech stack we use, how we build, what legacy baggage we’re carrying.”

A well-structured spec file typically includes the following sections:

# Project Spec File
## Project Overview
An order service for e-commerce scenarios, built with a mainstream
Java backend framework + persistence framework + relational database.
## Common Commands
- Start locally: the framework's built-in start command
- Run tests: execute the unit test suite
- Build/package: clean and package (tests may be skipped to speed up)
## Code Conventions
- Naming: camelCase for variables and methods, snake_case for database table names
- Layering: controllers handle only parameter validation and routing; business logic stays in the service layer
- Data access: no SQL string concatenation in business code; keep all queries in persistence-layer mapping files
## Known Conventions and Pitfalls
- Order creation timestamps are stored in UTC; the frontend must convert to UTC+8 for display
- Third-party payment callbacks must use HTTPS; use a tunnel tool for local integration testing

A spec file saves tokens because the agent’s context window is limited. If you don’t write it, the tool has to rebuild its understanding of the project every time by reading through code and asking repeated questions; once it’s written down, it’s like handing over the “onboarding manual” right at the start, eliminating a lot of back-and-forth confirmation. I ran a side-by-side comparison on a ~120,000-line Java project: before adding the spec file, changing a single piece of code often took three to four rounds of conversation just to establish context; after completing it, most tasks produced a solution that fit the project’s conventions in the first round, and the cost of back-and-forth dropped noticeably.

Key pitfall: a spec file is not better for being longer. I’ve seen someone write nearly 800 lines of spec, and then every conversation had to load all 800 lines into context up front, crowding out the window space that should have gone to the actual task. A spec file’s role is “high-frequency, stable, broad-impact” conventions — not a dumping ground for project documentation. Keep it to core information you can read in one screen, and leave rare edge-case rules to be explained in the specific task.

2. Tokens burn too fast — where is the cost actually going?

To understand token consumption, first accept one fact: the agent’s context window is a limited resource, and it’s often billed on the combined “input + output” total. Burning too fast usually comes from three sources:

• High startup rebuild cost: as noted above, lacking a spec file means re-explaining project background every round.
• Too much content stuffed in: dumping a large number of files, an overly long spec, and irrelevant history into context all at once, beyond what the task actually needs.
• Poor task breakdown: handing over one big, vague goal, so the model can only probe and read/write repeatedly — and the detours themselves burn tokens.

The corresponding optimization ideas are just as clear: solidify stable information into the spec file, bring in only files strongly related to the current task, and break big goals into small steps with clear boundaries. A common misconception is “feeding more context is safer.” In reality, context beyond what the task needs not only increases cost but can also dilute the model’s attention to key information.

3. What is the Model Context Protocol (MCP)?

The Model Context Protocol is a class of open standards that emerged in recent years, aiming to let AI agents connect to external data sources and tools in a unified, extensible way. You can think of it as a “standardized data and tool interface layer” prepared for the agent.

Before such a protocol existed, connecting each new tool (a database, a file system, some cloud service) usually meant writing a separate integration layer for it — high integration cost and hard to reuse. With a unified context protocol, tool providers only need to expose their capabilities according to the protocol, and the agent side can discover and call them consistently, greatly lowering the marginal cost of each new integration.

Its typical value is turning “the model can only chat” into “the model can operate a real environment”: reading internal knowledge bases, querying databases, and calling certain cloud services (common capabilities such as object storage, logging services, and monitoring/alerting) can all be connected through a standardized approach. Note that the protocol itself promises no specific capabilities; what you connect and what you can do depends on which tools and data you expose according to the protocol.

4. How do you give the agent “effective context”?

Many people complain that the tool “answers the wrong question,” and the root cause is often imprecise context. Effective practices include:

• Describe the goal, not the implementation: first state clearly “what effect to achieve,” leave “how to write it” to the agent, and constrain the style with the spec file.
• Point to key files: directly telling it which modules and files are involved is faster and saves more tokens than having it search globally.
• Provide a minimal example: giving an input and expected-output sample aligns expectations better than an abstract description.
• Advance step by step: break complex requirements into short chains like “understand first → change one thing → verify,” which is more controllable than issuing one big instruction at once.

5. How should large projects be handled?

The core challenge of a large codebase is being “locally correct but globally unaware.” A workable strategy is to split concerns by business module, actively scope the relevant directories and files in the conversation, and accumulate cross-module public conventions in the spec file (layering conventions, naming conventions, shared dependencies, and so on). Let the agent work within clear boundaries instead of blindly searching through hundreds of thousands of lines of code.

6. Should AI-generated code be reviewed?

It must be reviewed. There’s a gap between AI-produced code being “looks right” and “actually correct,” especially on boundary conditions, concurrency handling, and exception paths, where it tends to make assumptions. Treat AI output as a “high-starting-point draft”: first go through the logic and conventions, then verify with test cases. Any change that enters the main branch or production should go through the same review process as human-written code.

7. How do you safeguard data security and privacy?

This is unavoidable when enterprises adopt these tools. The basic principle: do not write sensitive information into files that will be read. Database passwords, keys, tokens, and the like should be injected through environment variables or a dedicated key-management solution; the spec file should only describe “what to use and how to use it,” never the real values. You should also confirm whether the data-handling policy of the chosen tool meets your team and compliance requirements — specifically, whether code and context are retained or used for other purposes.

8. How do you iterate efficiently when hitting errors?

Giving the agent the complete error message, reproduction steps, and relevant code snippets together is far more efficient than just saying “it errored.” The principle is “small steps, run fast”: change one thing, verify one thing, then move to the next step, avoiding too many changes at once that make the problem hard to locate. Having the agent first explain the cause of the error, then make the fix, is usually more reliable than just telling it to “fix it.”

9. How do you evaluate the return on investment?

Not every task is suited to the agent. What it’s good at is work with clear boundaries: boilerplate code, refactoring common patterns, writing tests, understanding unfamiliar code, and mechanical cross-file changes; while decisions involving deep architectural trade-offs, scarce business knowledge, or strong compliance judgment still need a human to lead. A reasonable evaluation approach is to pick a batch of representative real tasks and compare them, observing the combined benefit of “completion quality + communication cost + time saved,” rather than drawing conclusions from individual cases.

10. How does a team unify usage conventions?

The spec file should be brought under version control, committed and reviewed together with the code. Only when the team shares one spec can you avoid everyone writing their own and stepping into the same pitfalls. It’s also recommended to accumulate a shared “usage convention” within the team, clarifying which changes need human review, how sensitive information is managed, and how context is organized — so that the way the tool is used itself becomes part of the team’s collaboration norms.

---

Summary: Behind these ten questions is actually one main thread — treat AI coding tools as a new colleague who needs “mentoring”: reduce communication cost with a spec file, improve efficiency with precise context organization, and hold the line on quality and security with review and conventions. Nail these points, and these tools can truly go from an “occasionally-used toy” to “a productivity tool you can’t live without every day.”