Best Practices for Using AI

AI coding assistants such as Claude Code, GitHub Copilot, and ChatGPT have become everyday tools for hobbyists and professionals alike. This site itself was largely built with their help. Used well, they multiply what one person can build and maintain; used carelessly, they produce plausible-looking code you don't understand and can't debug. The practices below help you stay firmly in the first category.

Writing Effective Prompts

• State the Goal, Not Just the Task: "Add validation so users can't register with a weak password" gives the assistant more to work with than "add validation". Context about why produces better decisions about how.
• Provide Constraints Up Front: Mention the language, framework, versions, and conventions you're using. An assistant told "this is a Create React App project using functional components and CSS variables" won't suggest class components or inline styles.
• Share the Error, the Code, and the Expectation: When debugging, paste the exact error message, the relevant code, and what you expected to happen. Vague descriptions produce vague guesses.
• Iterate Rather Than Restart: If the first answer is close but not right, say what's wrong with it. Refining a response is usually faster and cheaper than starting over with a longer prompt.

CLAUDE.md and Project Context Files

Agentic tools like Claude Code read a CLAUDE.md file from the root of your repository at the start of every session. It's the single highest-leverage file you can write for AI-assisted development: instructions placed there apply to every future task without being repeated in every prompt. Other tools have equivalents (for example .github/copilot-instructions.md or AGENTS.md).

What belongs in a CLAUDE.md:

• Common Commands: How to build, test, lint, and run the project — so the assistant verifies its own work instead of guessing.
• Architecture Notes: A short map of the codebase: what lives where, how the pieces talk to each other.
• Conventions: Patterns the project follows (component structure, naming, styling approach) so generated code matches existing code.
• Gotchas: Quirks that would otherwise waste time — dead code to avoid, unusual configuration, environment requirements.
• Boundaries: Things the assistant should never do, such as committing secrets or pushing directly to main.

Keep it concise — a focused page beats an exhaustive manual, because the file is loaded into the model's context on every session (see token usage below). Update it whenever the project's structure or commands change, exactly as you would a README.

# CLAUDE.md (example skeleton) ## Commands npm start        # dev server npm test         # run tests before pushing ## Architecture React SPA in src/, Express API in server.js ## Conventions Functional components; shared styles in App.css ## Boundaries Never commit .env; develop on feature branches

Understanding Token Usage

AI models read and write text as tokens (roughly three-quarters of a word each). Everything counts against a finite context window: your prompt, files the assistant reads, its previous replies, and its reasoning. Tokens are also how usage is billed. Managing them well makes sessions cheaper, faster, and more accurate.

• Scope Tasks Tightly: "Fix the login redirect bug" lets the assistant read three files; "improve the app" invites it to read thirty. Smaller scope means less context consumed and fewer wrong turns.
• Start Fresh Between Unrelated Tasks: A long conversation carries its entire history forward on every exchange. When you switch topics, start a new session rather than dragging old context along.
• Point, Don't Paste: With agentic tools that can read your repository, reference files by path instead of pasting their contents — the assistant reads exactly what it needs.
• Match the Model to the Job: Use smaller, cheaper models for routine work (renames, boilerplate, simple queries) and reserve the most capable models for architecture, debugging, and complex refactors.
• Watch for Context Exhaustion: When a session grows very long, models may lose track of earlier details. Summarise progress and continue in a fresh session — a good CLAUDE.md makes this cheap, because the new session starts with the project context already written down.

Using Claude Code with GitHub

Claude Code runs in the terminal, in a browser session, or inside GitHub itself, and can operate directly on your repositories: reading code, running tests, committing, and opening pull requests.

• Work on Feature Branches: Have the assistant develop on a branch and open a pull request, never commit straight to main. You review the diff exactly as you would a human colleague's — this is the single most important habit.
• Let CI Be the Safety Net: With tests and linting running on every pull request (GitHub Actions, for example), AI-generated changes must pass the same bar as any other change before merging.
• Delegate Whole Tasks: Well-scoped issues — "add input validation to the register endpoint, with tests" — can be handed to Claude Code end-to-end: it explores the code, makes the change, runs the tests, and opens a PR for your review.
• Use It for Code Review: Asking the assistant to review a pull request catches real issues — unhandled edge cases, security problems, inconsistencies with the rest of the codebase — and it can respond to review comments with fixes.
• Keep Secrets Out of Reach: Store credentials in environment variables and GitHub Actions secrets, never in the repository. An assistant with repo access can read anything committed — including that .env file you meant to delete.

Reviewing AI-Generated Code

• Never Merge What You Don't Understand: If you can't explain what a generated change does, don't ship it. Ask the assistant to explain it — teaching is one of the things these tools do best.
• Verify Claims Against Reality: Models occasionally invent plausible-sounding APIs, configuration options, or library behaviour. If a suggestion looks unfamiliar, check the official documentation before relying on it.
• Demand Tests: Ask for tests alongside generated code. A test suite is your independent check that the code does what the conversation claimed it does.
• Watch for Drift: AI-generated code tends to introduce new patterns rather than reuse existing ones. Check that changes follow your project's conventions instead of quietly forking them.
• Security Still Applies: Generated code can contain the same vulnerabilities as hand-written code — injection flaws, missing validation, weak defaults. Review it with the same security eye, especially anything touching authentication or user input.

Knowing the Limits

• Knowledge Has a Cutoff: Models are trained up to a certain date. For fast-moving tools and new releases, verify against current documentation.
• Confidence Is Not Correctness: Models present wrong answers with the same fluency as right ones. Treat output as a well-informed draft from a colleague, not as an authority.
• You Own the Result: Whatever wrote the code, you ship it, you debug it at 2am, and your name is on the commit history. AI assistance changes how fast you work — not who is responsible for the work.

Conclusion: The skill of using AI tools well — clear prompts, good project context files, sensible token habits, and rigorous review — is now as much a part of the craft as knowing your editor or your shell. Invest in it the same way: deliberately, and with a healthy scepticism of anything that looks too easy.