Terminal AI Coding Assistants: 11 Practical Tips for Effective Use

Over the past year, AI coding tools have become more common in daily development. Terminal-based AI coding assistants are among the most representative categories. They run directly in the command line and can read and write project files, execute build and test commands, search code, analyze errors, and even generate commit messages. Developers can describe requirements and implement code within the same context without switching between an editor, browser, and terminal. Some teams also evaluate practical experience with these tools when hiring for engineering or agent development roles, not just conceptual knowledge.

However, many developers find the results inconsistent: simple tasks show clear efficiency gains, while cross-module changes or complex logic often go off track and require repeated correction. The problem is often not the model itself, but the way the tool is used: unclear goals, imprecise context, and insufficient control over the change process. This article does not focus on implementation principles. Instead, it covers 11 commonly used operations and techniques, explaining what problem each one solves, when to use it, and how to use it, to help developers who are just starting out avoid common pitfalls.

1. Start with the basics: startup methods and three work modes

1.1 Startup methods

These assistants are usually started from a project directory. After launch, they automatically treat the current directory as the workspace, identify the project structure, search code, and execute commands after authorization. There are three common startup methods:

• Start from the project root directory: suitable for daily development, allowing the assistant to see the full project structure.
• Start from a subdirectory: suitable when working on a single module, narrowing the search scope and reducing irrelevant context.
• Start with a history or session parameter: used to resume a previous conversation. See the session recovery section later in this article.

A good habit is to first confirm the current branch and workspace status from the project root directory, then start the assistant.

1.2 Three work modes

Most terminal assistants provide three work modes with different use cases:

• Default mode: the assistant can read files, search code, and usually requires confirmation before executing commands. It balances efficiency and safety and is suitable for most daily tasks, such as fixing an error, adding unit tests, or adjusting part of an API logic.
• Plan mode: the assistant only performs analysis and solution design without modifying code. It explains the implementation approach, affected files, and potential risks first, and proceeds only after confirmation. This mode is suitable for larger changes, such as adding a new feature module, changing a core data structure, or refactoring a shared component.
• Auto-execution mode: the assistant can perform multiple consecutive operations without step-by-step confirmation. It is the most efficient but also the riskiest. It is only suitable for trusted environments where changes can be quickly rolled back, such as one-off script cleanup, batch formatting, or experiments on temporary branches.

The principle for choosing a mode is simple: the larger and harder the change is to roll back, the more reason there is to use plan mode first. Many cases where “the AI broke the project” happen because the assistant was allowed to make changes immediately.

2. Use plan mode: think before acting

The most time-consuming part of coding is often not writing code, but figuring out how to write it. The value of plan mode is that it moves this work earlier and leaves human review in the loop.

An effective plan should include:

1. Requirement understanding: restate the goal in one or two sentences to avoid direction drift.
2. Change list: list the files to be added or modified, along with their responsibilities.
3. Implementation steps: describe them in execution order, keeping each step as small and verifiable as possible.
4. Risks and impact: explain the effect on existing features, data structures, and APIs.
5. Validation method: specify which builds, tests, or manual checks will be used to confirm the result.

You can provide a template directly in the prompt. For example:

Enter plan mode first and do not modify any files. Output the plan in the following format:
1. Requirement understanding: restate the feature I want to implement in one sentence;
2. Change list: list the new or modified files and their responsibilities;
3. Implementation steps: describe each step in order, and make each step independently verifiable;
4. Risk points: list other modules that may be affected;
5. Validation method: explain how tests or manual checks will verify the result.
Wait for my confirmation before implementation.

When reviewing the plan, focus on three points: whether edge cases are missing, whether the scope exceeds the requirement, and whether the validation method can actually prove the feature is correct. Once the plan is reasonable, switch back to default mode and proceed. If deviations appear later, it is easier to identify which step went wrong.

3. Requirements unclear? Let the assistant interview you

In practice, a lot of rework is not caused by insufficient model capability, but by vague requirements, such as “optimize this API” or “make this page look better.” The more ambiguous the requirement, the more the assistant has to guess, and the less stable the result becomes.

A better approach is to temporarily switch the assistant from “executor” to “interviewer”: ask it to clarify the requirements before making changes. You can use a prompt like this:

Before making any changes, act as a product manager and technical lead. Help me clarify the requirements by asking questions.
Ask no more than 3 questions at a time, focusing on: target users and use scenarios, feature boundaries, and non-functional requirements such as performance and compatibility.
After I answer, output a requirements confirmation checklist. Only start implementation after both of us confirm it.

This two-way clarification brings three benefits:

• Expose hidden assumptions: premises that seem obvious to you may not be known to the assistant, such as whether a field can be null or whether an API must remain compatible with an old version.
• Force requirements to become concrete: “look better” can be turned into actionable criteria such as color scheme, spacing, and interaction feedback.
• Create reusable input: after confirmation, the requirements checklist can be pasted directly into the project convention file, as described later in this article. The same questions do not need to be asked again for similar tasks.

4. Specify files precisely: use @ references instead of vague descriptions

If you only say “the login page” or “the order-related service,” the assistant may spend time searching the whole project, consuming context and sometimes locating the wrong target. In terminal assistants that support file references, using @ with a file path is one of the simplest and most effective ways to improve speed:

Analyze the inventory deduction logic in @src/service/OrderService.java.
Point out unhandled concurrency scenarios and explain the possible consequences.

Additional techniques can improve results further:

• Multi-file references: reference the API definition, implementation class, and test file together, such as @src/api/OrderApi.java @src/service/OrderService.java @test/OrderServiceTest.java, so the assistant can judge the impact of changes with complete context.
• Directory references: when you need to understand the overall structure of a module, referencing a directory is more efficient than describing individual files one by one.
• Locate first, then expand: for large projects, first ask the assistant to list relevant files, then select key files for precise reference. This avoids inserting too much irrelevant code at once.

More context is not always better. Irrelevant code not only dilutes key information but also consumes the context window. Precise references are the first lever for controlling cost and improving hit rate.

5. Use deep thinking for complex features: reason before acting

When a task involves multiple coupled modules, complex state transitions, or hidden bug investigation, the assistant may easily “think one step and act one step” in default mode, gradually drifting off course. In this case, enable deep thinking or extended reasoning so that the assistant performs more thorough reasoning before making changes. For example:

Enable deep thinking. This is a state synchronization problem that spans three modules.
First map all possible state transition paths and exception branches, then propose a fix plan and explain the impact of each option on existing callers.

There are a few points to note when using this mode:

• Enable it by difficulty: simple tasks such as formatting, renaming, or adding comments do not need deep thinking. Enabling it only increases time and token consumption.
• Use it together with plan mode: deep thinking helps “think comprehensively,” while plan mode helps make the solution reviewable. Combining them works best.
• Split very large problems: if the problem is too large, even more reasoning will not solve it effectively. Break it into sub-problems by module and solve them one by one.

6. Project memory file: avoid explaining the project every time

Almost every team has some unwritten project rules: how directories are organized, how code should be written, how tests are run, and which directories should not be touched. If you have to explain these rules again in every new session, it is not only inefficient but also easy to create inconsistencies.

The solution is to maintain a project convention file in the project root directory. These assistants usually read it automatically when starting. The common filename is CLAUDE.md, and some compatible setups also use AGENTS.md as the entry file. It is essentially a “project manual” for the assistant. A good file should include:

# Project Conventions
## Project Overview
- Business: Order center backend service, providing order creation, query, and refund APIs
- Tech stack: Java 17 + Spring Boot 3.x + MyBatis + MySQL + Redis
## Common Commands
- Local start: ./scripts/start.sh
- Full test suite: ./scripts/test-all.sh
- Unit test for a single class: ./scripts/test-one.sh <Class Name>
- Lint: ./scripts/lint.sh
## Code Style
- Use four-space indentation; keep lines under 120 characters
- Public methods must include Javadoc
- Do not use wildcard imports
## Change Rules
- Database changes must include a rollback script
- Changes to external APIs must update the API documentation
- New logic must have corresponding unit tests
## Do Not
- Do not modify generated code under the generated directory
- Do not modify production configuration files directly
- Do not introduce third-party dependencies that have not been evaluated

There are four points to keep in mind when using this file:

1. Keep it concise: this file consumes context in every session. Only keep high-frequency and necessary information, and avoid turning it into a long document.
2. Manage it in layers: put personal preferences in the user-level directory, team rules in the project-level file, and module-specific rules in the corresponding subdirectory.
3. Update it with the project: when commands or directory structures change, update the file promptly. Outdated conventions can mislead the assistant.
4. Allow self-maintenance: you can ask the assistant to help maintain it, for example: “Add the project conventions confirmed in this session to the project convention file. Keep it concise and do not duplicate existing entries.”

7. What if the change goes wrong? Compare three undo methods

When letting AI modify code, always think in advance about “what to do if it goes wrong.” There are three common rollback methods, each with different use cases:

Undo method	Scope	Can undo uncommitted changes?	Traceability	Suitable scenarios
Version control rollback (revert/reset)	Committed code	No	Strong, with full commit history	A committed change is found to be wrong
Assistant built-in rollback, returning files and conversation to an earlier point	Changes in the current session	Yes	Medium, recoverable within the session	A step is wrong during multiple consecutive changes
Manual undo	A single file or snippet	Yes	Weak, relies on personal memory	Small, localized accidental changes

Selection principles:

• Use version control as the fallback: before asking the assistant to make larger changes, commit or stash the current code so there is always a clean checkpoint.
• Use in-session rollback for quick correction: if the assistant modifies multiple files and only later you find the direction is wrong, rolling back to an earlier point is usually faster than manually fixing line by line.
• Use branch isolation: perform high-risk changes on a separate branch, and merge back to the main branch only after validation.

No matter which method you use, it is recommended to commit once after the assistant completes a group of changes and clearly state the intent of the change. Even if you need to roll back later, there will be clear checkpoints to follow.

8. The assistant becomes confused? Compact first, then clear

In long sessions, the assistant’s performance gradually degrades: it forgets earlier conventions, repeatedly modifies code that has already been fixed, or gives solutions inconsistent with the project style. This is usually not because the model has become less capable, but because the context has been filled with historical messages, and key information is buried.

To handle this, troubleshoot in the following order:

1. Check context usage first: most terminal assistants display the current context usage ratio or warn when approaching the limit. If usage stays above 70% for a long time while the task remains complex, it is time to intervene.
2. Try compaction first: compaction summarizes the current session history, retaining the task goal, completed changes, and key conclusions while freeing up space. It is suitable for scenarios where the task is not finished but context is tight, such as long-chain problem investigation.
3. Consider clearing next: clearing starts a new context and is suitable when the current task is complete and you want to switch to an unrelated task. Before clearing, make sure important conclusions have been written into the project convention file or commit records.
4. Persist information before switching sessions: write decisions, TODOs, and known pitfalls into documents or comments. A new session can quickly continue with these materials instead of relying on memory.

A practical rule is: if you are stuck on the same task, compact; if you are switching to a different task, clear.

9. Will closing the terminal lose the conversation? Use session recovery

Conversations with terminal assistants are usually stored locally by default. Closing the terminal does not necessarily mean losing them. Through session recovery, you can reopen a recent session and continue with the previous context. This is useful in several scenarios:

• Discuss a solution during the day and continue implementation the next day.
• Leave a debugging session midway and return without re-describing the background.
• Hand over a session record to another person during team transitions.

Note that session recovery depends on local session records. Clearing local data or switching to a different work machine may make recovery impossible. Therefore, important conclusions should still be written into code, commit messages, or documentation. Session records are better suited as process materials rather than the only knowledge carrier.

10. Who reviews the code? Use subagents for code review

AI-generated code must be reviewed. This is a shared understanding. However, asking the main session to review the code it just wrote often has limited effectiveness: it is influenced by its existing approach and may overlook its own implementation.

10.1 What is a subagent

A subagent is an assistant instance that runs in an independent context, completes a specific task, and returns the result to the main session. Its key value is context isolation: the reviewer does not see the trial-and-error and temporary compromises during implementation, but only faces the final code, giving a perspective closer to that of a new colleague. In addition, subagents can often run in parallel, making them suitable for reviewing multiple modules at once.

10.2 Create a code-review subagent

You can define a dedicated review role in the project’s subagent configuration directory using Markdown with metadata:

---
name: code-reviewer
description: Review code changes before commit, covering correctness, edge cases, performance, and security
tools: Read, Grep, Glob   # Grant read and search permissions only; no write access
---
You are a strict code reviewer. Follow these review rules:
1. First read the changed files and their callers, then confirm the context before making conclusions;
2. Check the following dimensions one by one: correctness, edge cases, concurrency and resource release, exception handling, performance, security (injection, authorization bypass, sensitive information), readability, and test coverage;
3. Every comment must include: file and line number, issue description, possible impact, and suggested change;
4. Mark uncertain conclusions as "to be confirmed"; do not speculate;
5. Output findings by severity: blocking / suggestion / note.

There are two key design points:

1. Grant read-only permissions: this avoids generating additional changes during review.
2. Require structured output: this allows people to quickly identify which issues must be fixed first.

10.3 Use the subagent to review code

Use the code-reviewer subagent to review the current uncommitted changes. Focus on concurrency safety and exception handling, and sort the output by severity.

For large changes, you can launch multiple review tasks in parallel by module, then aggregate the results into a single review report.

10.4 What is the difference between subagents and skill extensions

These two concepts are often confused, but they solve different problems:

Comparison dimension	Subagent	Skill/custom instruction
Core purpose	Isolate context and complete a subtask independently	Package reusable instructions, scripts, and resources
Execution model	Runs in an independent context and returns conclusions	Loads and executes in the main session context as needed
Typical use cases	Code review, batch search, parallel analysis	Unified code style, calling internal tools, generating template documents
Selection criteria	Use when the task needs an independent perspective or parallelism	Use when the task needs a consistent approach or fixed workflow

A simple rule: use a subagent when you need an independent perspective; use a skill extension when you need to do things the same way every time. They can be combined. For example, use a skill extension to standardize commit message generation, then use subagents to check whether modules comply in parallel.

11. Implementation advice: turn personal techniques into team norms

These techniques are often first discovered by individuals, but to create lasting benefits, they need to become team conventions:

• Standardize the project convention file: put the tech stack, commands, coding rules, and prohibitions into the repository so that new members and AI can align quickly.
• Make planning the default: in team norms, clearly require that changes involving multiple files or core logic must produce a plan before implementation.
• Commit in small steps: limit the scope of each AI change, commit after completion, and keep clear rollback points.
• Do not skip review: AI-generated code should follow the same review standards as human-written code, with extra attention to edge cases and security.
• Integrate with existing development processes: combine existing engineering capabilities such as code hosting, continuous integration, artifact management, logging services, and monitoring/alerting with AI-assisted development, so that code automatically passes through build, test, and static analysis, forming a closed loop of generation, validation, release, and observation.
• Manage permissions and data security: configure directory and command permissions reasonably, and avoid placing sensitive information such as keys and production configurations directly into the context.

Conclusion

The difference in results from terminal-based AI coding assistants largely depends on the user’s method rather than the tool itself. These 11 techniques can be summarized into three main lines:

• Say it clearly: use plan mode, clarifying questions, precise file references, and project convention files to give the assistant accurate and complete input.
• Keep control: use branch isolation, timely commits, in-session rollback, and independent subagent review to ensure every change is verifiable and reversible.
• Manage context: use context usage monitoring, compaction and clearing strategies, and session recovery to keep context effective for long-running tasks.

It is best to start with two low-cost, high-return practices: “commit before making changes” and “maintain a project convention file.” Once these habits are stable, gradually introduce subagent review and team norms. Then terminal AI coding assistants can move from occasionally useful tools to a reliable part of daily development.