# 18 agentic development tips for Claude Code > Handing real engineering work to an agent like Claude Code takes discipline. 18 tips to keep code quality and control without losing speed. José Obregón · 2026-10-01 · https://joseobregon.me/blog/agentic-development-tips-claude-code/ Handing real engineering work to an agent like **Claude Code**, with **GitHub** at the center of the workflow, takes discipline and structure. These 18 tips help you keep code quality and control of the architecture without losing speed. ## Prepare ### 1. Start with the harness and the repository context Claude Code is only as good as the context and tools you give it. Before you ask for the first feature: - **Explicit context:** document the architecture, conventions, constraints, preferences, common commands, tools, skills and business rules. Keep a concise `CLAUDE.md` (which can import an `AGENTS.md` with `@AGENTS.md`) at the root (and in key subdirectories in a monorepo), and link all the project's important documentation from there, so Claude reads it only when it needs it. - **Tools and checks:** give Claude the knowledge and permissions to run scripts, type checks, linters, formatters, tests and skills. That way it can check for itself whether it broke something and iterate until it hands you a clean solution. These checks bring determinism to a process that, by nature, doesn't have it. - **Integrations:** with `gh` or the GitHub MCP server, Claude works directly on issues, PRs, reviews and CI runs. Add other MCP servers to suit your stack: Slack, Gmail, Confluence, Jira, your database or your error monitoring tool. - **Permissions:** give Claude as much autonomy as you can in an isolated environment; the fewer confirmations it needs, the smoother and more productive the work. Start with [auto mode](https://code.claude.com/docs/en/permission-modes), where a classifier reviews risky actions for you, and add [`/sandbox`](https://code.claude.com/docs/en/sandboxing) to isolate shell commands. Use good judgment, though. ### 2. Pick the model for the task | Model | When to use it | | ---------- | ----------------------------------------------------------------------------------------------------------------- | | **Haiku** | Simple, repetitive tasks, mechanical refactors, quick questions about the codebase | | **Sonnet** | Well-scoped tasks, UI changes, implementation from very detailed specs | | **Opus** | More complex development, long sessions, deep understanding of the codebase | | **Fable** | Complex architecture, repo-scale refactors, critical incidents, ambiguous problems or ones with no clear solution | > Models current as of October 2026. You don't have to use a single model per task: you can plan with Opus or Fable and implement with Sonnet. The model isn't the only lever on cost: use [`/effort`](https://code.claude.com/docs/en/model-config) to set how much reasoning Claude applies, higher for tricky cases and lower for quick back-and-forth, and check [`/usage`](https://code.claude.com/docs/en/costs) to see where your tokens go. ## Plan ### 3. Plan before you implement Use **plan mode** so Claude explores the repo, identifies the affected files and edge cases, validates assumptions and discusses trade-offs without changing anything. Iterating on ideas and making decisions with Claude at this stage saves you time, money and effort. ### 4. Turn the plan into a spec (`.md`) Before implementing, put what you agreed on in a file (for example, `specs/feature-x.md`). A good spec covers: - **What:** the concrete goal. - **Why:** the problem it solves and the value it brings. - **For whom:** the users, agents, services or teams affected. - **Guardrails:** limits and constraints; what must not be touched, decisions already made, dependencies that aren't allowed, and security or performance requirements. - **Acceptance criteria:** a verifiable checklist to call the task done. The spec is a **living** document: if a decision changes during implementation, an edge case appears or a criterion is adjusted, Claude must update the spec at that moment. An out-of-date spec is more confusing than no spec at all. Besides aligning the team, the spec works as persistent memory that survives every context cleanup. ## Build ### 5. Manage your context window A long session that mixes tasks piles up failed attempts and old logs that degrade the model's attention, increase hallucinations and make every message more expensive. Clear the context with `/clear` when you close a subtask or move from the spec to the implementation, or summarize it with `/compact` if you need to stay on the same task. To keep control of the context window, use `/btw` for quick questions that don't need to stay in the history, delegate exploration and research to subagents (they work with their own context and only return the result), and separate parallel tasks with `git worktree` (tip 9). If Claude drifts, press `Esc` to stop it without losing what it has done, or use [`/rewind`](https://code.claude.com/docs/en/checkpointing) to roll the code, the conversation or both back to an earlier point. After two failed corrections, don't try a third: run `/clear` and write a better prompt with what you learned. ### 6. Write commits with context and traceability At the speed Claude generates code, the Git history becomes one of the team's main sources of context. On top of [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/), which feed automatic changelogs, require a body of 2 to 4 lines with the **what** and the **why**: that's what makes `git log` useful. Always attribute the commit to Claude and the exact model used with the `Co-Authored-By` trailer, so GitHub shows it as a co-author of the change. This traceability lets you audit the code with context and compare which models perform best in each part of the stack. ### 7. Require detailed, up-to-date PRs Have Claude write the PR: the problem, a link to the spec, technical decisions and steps to test. If new commits come up during review, ask it to update the description so it reflects the real state before the merge. Ask for small, incremental PRs: an agent can generate huge diffs that nobody truly reviews. If a change grows too much, split it into several PRs. PRs are a fundamental part of the context you give Claude: when it comes back to a module, that's where it finds what changed, why, and which alternatives were discarded. ### 8. Link every PR to a GitHub issue No change should appear out of nowhere: every requirement, bug or improvement starts as an issue, and every PR closes one. That way anyone can go from the commit to the PR and from there to the issue, where the formal request, the owners, the priority and the whole discussion behind the decision live: full traceability from end to end. Organize the issues on a **GitHub Projects** board with statuses and priorities to keep a tidy backlog that shows at all times what's being done and what comes next. Claude can keep it up to date by moving issues between statuses and adjusting priorities for you. Just as commits and PRs give Claude the context of what's been done, issues give it the context of what's coming. Once you set up [`anthropics/claude-code-action`](https://github.com/anthropics/claude-code-action), just mention `@claude` in an issue and it implements the change on a branch and leaves you a link to open the PR; mention it in a PR and it applies the changes requested in the review. ### 9. Work in parallel with `git worktree` One worktree per branch lets you run several Claude Code sessions at once, with no `git stash` and no waiting: while Fable does a heavy refactor on one branch, you fix a quick bug with Sonnet on another. With [`claude -w feature-x`](https://code.claude.com/docs/en/worktrees), Claude Code creates the worktree and starts the session in it. Keep in mind that each worktree needs its own installed dependencies, and different ports if you start servers. ### 10. Package repetitive knowledge into skills Instead of repeating complex prompts or bloating `CLAUDE.md` with one-off cases, turn them into [skills](https://code.claude.com/docs/en/skills): creating safe migrations, auditing OWASP vulnerabilities, building components that follow your design system, preparing a release, doing a code review (tip 11), creating PRs or issues. Claude loads them only when the task calls for them, saving context and standardizing the team's quality. Skills also bring **consistency** to the workflow: instead of improvising a different procedure each time, Claude starts from the same steps, templates and criteria, which makes results more predictable. They're still instructions, not guarantees: for what can't fail, use hooks (tip 16). ## Review ### 11. Always do a code review Never accept the first code Claude generates. Run the review in a clean context window, free of the bias of the session where the code was written. [`/code-review`](https://code.claude.com/docs/en/code-review-local) does just that: it reviews the diff in a subagent that never saw your conversation. Ideally, also have your own code review skill that always verifies the same points: security, performance, logic, error handling, code cleanliness, and compliance with the repo's conventions and the spec. It's also a good idea to add a review with another model: if you implemented with Sonnet or Opus, review with Fable. A different model catches mistakes the original tends to miss. ### 12. Require real E2E tests Don't rely on unit tests and code coverage alone: agents tend to overuse mocks and leave tests green even when the real integration is broken. Require E2E tests (for example, with Playwright) on the critical flows. They are the safety net for refactoring fast without breaking the business. ### 13. Treat external content as untrusted If Claude reads issues, PRs, comments or web pages written by third parties, that content can include malicious instructions (prompt injection). Limit what Claude can do while it processes public content, and review every new dependency it adds. ## Automate ### 14. Automate maintenance with scheduled tasks - **Monitoring:** with `/loop`, Claude Code re-runs a prompt at an interval while the session is open, so it can check asynchronous processes, like a PR's CI checks, and act when they finish, either fixing a failure or moving on to the next step. - **Periodic maintenance:** let Claude review Dependabot alerts, the third-party dependency audit and code scanning alerts, and **open the PR with the fix**, ready for your review. - **Backlog triage:** let Claude periodically classify and label new issues, detect duplicates and propose priorities, so the backlog from tip 8 stays tidy with no manual effort. - **Up-to-date docs:** let Claude periodically check that `CLAUDE.md`, the specs and the documentation reflect the real state of the code, and open a PR with the fixes. For periodic tasks that don't depend on an open session, use GitHub Actions with `anthropics/claude-code-action` and a `schedule` trigger, or [`/schedule`](https://code.claude.com/docs/en/routines) (in research preview), which runs them in Anthropic's cloud even with your laptop closed. ### 15. Automate checks in pre-commit, pre-push and GitHub Actions Here, `pre-commit` and `pre-push` are Git hooks, not Claude Code hooks (tip 16). Each gate gives Claude immediate feedback to correct itself before the mistake reaches review: - **`pre-commit` and `commit-msg` (seconds):** formatting and lint on the changed files, secret scanning and Conventional Commits validation. - **`pre-push`:** global type check, build and affected unit tests. - **GitHub Actions (the final gatekeeper):** deep static analysis, coverage, lint of the whole repo and the full suite on every PR. Mark them as required checks in the branch protection for `main` so nothing merges on red. If something fails, Claude can read the run's logs and propose the fix. The sooner a defect is detected, the faster and cheaper it is to fix. ### 16. Use hooks for what can't fail The rules in `CLAUDE.md` are instructions the model can overlook; [Claude Code hooks](https://code.claude.com/docs/en/hooks-guide) always run. Use them to format and validate after every edit, protect sensitive files or run checks before calling a task finished. They are the most deterministic piece of the whole workflow. ## Stay in control ### 17. Keep improving your workflow Agentic development changes week by week. Regularly review what fails most often, where tokens are wasted and which tasks still need manual work, and apply the fixes in `CLAUDE.md`, the skills or the automations. Claude Code's context is never finished: it improves along with the team. ### 18. The responsibility is still yours Claude implements, but the code that reaches `main` is yours. Understand every important decision, and don't merge anything you couldn't defend in a review. The agent's autonomy works because at the end of the workflow there is someone with judgment. ## Conclusion Mastering agentic development isn't about delegating blindly but about designing a system: context engineering, traceability, documentation, skills, automation and continuous improvement. But above all: **judgment**. That way, Claude Code's speed always works in favor of the project's quality and maintainability.