Claude Code is a software development agent which runs on your local machine. My experience is that when people first start using Claude Code, they have a bad experience with it, as it can be too easy to assume that you don’t need any knowledge to be productive. Beginners tend to write very short, “one shot” prompts, and then get surprised when they don’t get a good result. As an example, I have a million line plus project, where I want upgrade from Mockito 3 to Mockito 5. A really *bad* way to use Claude Code would be to:

• Do no prep
• Write an insanely short, one shot prompt, like “upgrade this project from mockito 3 to 5”

this is what beginners tend to do. But actually, I think there is quite learning curve to being productive with Claude Code. This post is an attempt to give newcomers some more structured guidance. The topics I’ll cover will be:

1. Using the help and understanding the different Claude Code commands
2. The importance of CLAUDE.md and other docs.
3. Using MCP servers to extend Claude, specifically:
   1. Querying git, Jira, Confluence etc
   2. Using Chrome
   3. Querying a database
   4. Getting API docs with context7

Once I’ve covered those topics, I will go through some examples of good and bad prompts, and what I consider a standard workflow. (No point doing this until you understand the basics.)

Installation and starting Claude Code

Claude Code installs using NodeJS. Install instructions here:

Claude Code setup

Once you have it installed, you start Claude Code from the base of the project you want to work on by typing “claude”. This starts Claude in normal mode, where it can perform read only actions, but will ask you for permission to do anything more. Claude support four modes, which you can cycle through using SHIFT + TAB. They are:

• Normal
• Accept Edits
• Plan Mode – zero write permissions
• Bypass Permissions or “dangerous” mode

I prefer to run in dangerous mode, so I have set up an alias in my Mac .zshrc:

alias claude-power=claude --dangerously-skip-permissions

To me, one of the most important things with any new tool is understanding how to acccess the help. With Claude, you do this by typing /help. This gives you a set of three help pages which you can tab through. I’m not going to go through every command, but will highlight the ones I think are important. Basic commands:

• @ – allows you to add any file to Claude’s context – this is very commonly used if you have written a plan or other notes in a previous session, and want to load them back in
• ! – bash mode – allows you to run a terminal command without dropping out of the Claude prompt
• # – to memoize. i.e. add to CLAUDE.md

Most commands in Claude are slash commands. Ones to highlight:

/context - Show current context usage
/compact - Compact your context. You'll use this after you have done a planning session and want to compact your context to just include the necessary info.
/clear - Clear context.
/export - Export context to a file.
/add-dir - Add another directory to Claude - useful if you have a task across multiple repos.

Note that you can also use Claude to help you use Claude! But you have to know the right way to do it! Claude will NOT search the internet or its own docs unless you tell it to. Suppose you asked Claude to write some code and it messed up. Simply typing “how could I have written that better” will only search the current LLM model, which could be several months old, so won’t even know about recent Claude features. Whereas typing “search the claude docs and the internet and tell me how I could have avoided you using a mock inside an integration test” is a far more precise question that will get Claude to access its most current docs.

CLAUDE.md and other docs

When people first start using Claude, they often give it a prompt and don’t understand why it gets something wrong. Perhaps the most common reason is because they have not provided enough background information. You and fellow developers may have worked on your codebase for many years. Claude is coming to it new. You can and should help it out by providing docs. The first step is to write a CLAUDE.md file. You can actually generate this using Claude and the /init command, but you absolutely should review it, and continue to improve it over time.

For a large project, your CLAUDE.md could become pretty big. This actually creates the opposite problem. Because CLAUDE.md is loaded automatically every time you run Claude, you could be confusing it with too much irrelevant information. So for a large project, you should break down your docs into multiple markdown files. There are different ways to do this. Some teams like to have a CLAUDE.md in the root of different modules. Whilst I understand the argument that the docs are closer to the code they pertain to, for my team, I prefer to have a docs folder with the files named as per the topic they cover. This makes it easier to see what areas we already have covered. So, for example, we have five markdown docs for tests – one for each kind of test we have in our repo. Our top level CLAUDE.md explains the five different kinds of test, and points to the docs for each one, so Claude can dynamically load the info if it needs it.

Extending Claude with MCP servers

The MCP server protocol is an open standard for agent communication. It allows you to connect an agent to numerous different tools. You can configure MCP servers in the claude files for a project, or in your global claude config. Once added, you can use the /mcp command to administer them. MCP servers can use a lot of context, so you should disable them all by default, and then just enable the one(s) you want to use for a particular task. The Claude docs have an intro to MCP here:

https://code.claude.com/docs/en/mcp

Querying git, Jira, Confluence etc

We use the Atlassian suite, so the Atlassian MCP allows us to connect to git, Jira and our Confluence docs:

https://support.atlassian.com/atlassian-rovo-mcp-server/docs/getting-started-with-the-atlassian-remote-mcp-server/

If you are using GitHub or GitLab, you can configure their MCP servers for similar connectivity. Claude won’t use an MCP server unless you tell it to. For most tasks I work on, I probably want Claude to search our wiki before it writes a plan. So I’ll explicitly say “use the atlassian mcp server to search our confluence wiki” as part of my prompt.

Using Chrome with Chrome DevTools

https://developer.chrome.com/blog/chrome-devtools-mcp

Sample use cases for Chrome integration could include: starting your app and performing a quick test once some work is done, or helping to write Selenium or Playwright tests for the app by inspecting your browser DOM

Querying a database with DBHUB

https://github.com/bytebase/dbhub
Add this with:

claude mcp add --transport stdio db -- npx -y @bytebase/dbhub --dsn "sqlserver://username:password@host.com:1433/your_db_server"

You might wonder why you would need to bother connecting Claude to a db? You already know how to run queries, and you will have a SQL client, so what is the benefit? Well, remember how earlier I said you should be adding plenty of docs to your repo – you can add as much info as you want about the DB structure and useful queries. Then a new developer doesn’t have to spend time figuring out how to construct a query, they can ask Claude, and Claude can use your docs to understand the structure and assist with writing the query.

Getting up to date docs with Context7

https://github.com/upstash/context7

Especially useful for tasks like upgrading from one version of a library to another, where you need to understand all of the changes.

Workflow

Now you understand all of the basic functionality of Claude, we can revisit workflow. The worst workflow is a terse, one shot prompt. Earlier I gave my own example “upgrade from mockito 3 to 5”. Given all of the above, a better way to start this task might be a prompt like this:

I want to upgrade this project from mockito 3 to 5. please search the internet, and use the atlassian mcp server to search our confluence wiki, and use the context7 mcp server to get the latest mockito docs, to help me write a plan to do this. the plan should clearly list all changes between mockito version 3 and 5. in particular, it should highlight changes that will cause compilation failures, such as classes that have been removed, methods removed or classes moved to different packages. separately it should highlight any runtime behaviour changes. for any runtime behaviour change, please search our code and tell me if we will be affected and if so, what changes to our code will be required. I want to make the minimal amount of changes possible, so if functionality is deprecated, but not removed yet, please highlight in the plan, but the plan should state it will not be updated.

Writing the plan is unlikely to be a one step process. Claude will come back with an initial plan which you can review. You can tell it to remove things, or highlight things it has missed that need to be assessed and added. Then once you are happy with the plan, you can write it to a markdown doc, then use /clear to clear your context, disable unnecessary MCP servers, to free up space, and then use @ to reload this plan into the context. You now have as much free context as possible to actually execute the plan.

Wrap up

I hope this has given you a good overview of the basics of Claude Code setup and workflow and you will enjoy learning Claude and gradually refining your own workflow. There are several topics I haven’t covered yet, such as skills, sub agents and plugins. Time permitting, I will cover these in a future post!