Getting Started with AI Tooling

A practical guide for integrating AI into your development workflow. You're developers — this isn't going to explain what a terminal is. It's going to show you how to use Claude Code to move faster, catch more, and automate the tedious parts of your day.

---

1. Install and First Run

# Install Claude Code
npm install -g @anthropic-ai/claude-code

# Navigate to any project
cd your-project

# Let Claude scan the project and generate a CLAUDE.md
claude init

claude init scans your repo — tech stack, directory structure, build files, tests, existing docs — and generates a CLAUDE.md with sensible defaults. Review it, tweak it, commit it. Now every developer on the team gets that context automatically.

Start a Session

claude

That's it. You're in a session. Claude can see your project files, run commands, and interact with your codebase.

---

2. What a Session Actually Looks Like

If you've never used a CLI AI tool, you might not know what to expect. Here's a realistic interaction — starting from a real problem and working through to a fix.

Start with the symptom — let Claude investigate:

You:    Orders are getting rejected from Cirro. Look in DataDog
        and find what's going on.

Claude: [queries DataDog logs for Cirro export errors]
        Found 23 rejected orders in the last 2 hours. They're all
        failing with: "Invalid shipping_method: null"
        Affected orders: PSA1804221, PSA1804238, PSA1804245...
        All came through SFCC.

Ask why — Claude traces across systems:

You:    Why are SFCC orders coming through without a shipping method?

Claude: [searches codebase for SFCC shipping method mapping]
        Found it. In ShippingMethodMapper.java:63, the mapping handles
        "EL_SMALLPARCEL" but SFCC recently started sending "GC_PARCEL"
        which isn't mapped. It falls through to null.

Tell it to fix — Claude writes code and shows you the diff:

You:    Fix it. Map GC_PARCEL to our standard shipping and add a
        fallback so unmapped methods don't blow up.

Claude: [reads the file, writes the fix, shows you the diff]
        Added "GC_PARCEL" → "STANDARD" mapping and a default fallback
        that maps unknown methods to "STANDARD" with a warning log.

Ship it — Claude handles the full workflow:

You:    Looks good. Write a test, commit it, and open a PR.

Claude: [writes test, runs test suite, commits, pushes, creates PR]
        PR created: github.com/PopSockets/camel-integrations/pull/142
        Should I reprocess the 23 rejected orders?

You started with a symptom, Claude investigated across systems (DataDog → codebase), found the root cause, fixed it, and offered to handle the fallout. You stayed in control — Claude proposes, you approve.

No context-switching between DataDog, your editor, terminal, browser, and Jira. It all happens in one conversation.

---

3. CLAUDE.md — Your Contract with Claude

CLAUDE.md is the most important file in your AI workflow. It's a set of directives Claude reads at the start of every session. Without it, Claude is a capable but uninformed developer who knows nothing about your project, your conventions, or your rules. With it, Claude starts every session already aligned with how you work.

What Goes in CLAUDE.md

Here's a realistic example for a PopSockets project:

# CLAUDE.md

## Project
Camel integration service — handles order flow between OMS, Cirro (3PL),
and EDI trading partners. Spring Boot 3.x, Java 17, Azure Service Bus.

## Build & Test
- `./mvnw clean install` — build and run tests
- `./mvnw test -pl edi-processor` — test specific module
- Tests require local Docker (Testcontainers for Service Bus emulation)

## Conventions
- DTOs go in `*.dto` packages, never reuse across bounded contexts
- All Service Bus messages must include a traceId header
- Error handling: catch at the controller level, log with structured JSON
- Use `@Slf4j` for logging, never `System.out`

## Safety
- NEVER execute DELETE, DROP, or TRUNCATE without listing affected
  records and getting explicit confirmation
- NEVER force push or rebase shared branches
- NEVER modify production config files without confirmation
- Always run tests before committing

## Workflow
- Every feature needs a Jira ticket — if one doesn't exist, ask me
- Branch naming: `feature/PROJ-123-short-description`
- All PRs require tests and documentation updates
- Deploy to staging first, never push directly to production

The difference between a lazy CLAUDE.md and a good one is enormous. A lazy one says "Spring Boot project." A good one tells Claude your build commands, your naming conventions, your safety rails, and your workflow. Claude follows these directives literally — the more specific you are, the more useful it becomes.

CLAUDE.md Inheritance

Claude reads CLAUDE.md files at multiple levels and merges them top-down:

~/.claude/CLAUDE.md                                    # Global — your personal defaults
  └── ~/popsockets/CLAUDE.md                           # Org — shared across all PS projects
        ├── ~/popsockets/integrations/camel/CLAUDE.md  # Project-specific
        ├── ~/popsockets/oms/CLAUDE.md                 # Project-specific
        └── ~/popsockets/pop-docs/CLAUDE.md            # Project-specific

Global (~/.claude/CLAUDE.md) — rules that apply everywhere. Safety protocols, communication preferences, tools you always want available. Write these once and forget about them.

Org/workspace level — conventions shared across all PopSockets projects. Tech stack assumptions, shared naming patterns, team rules.

Project level — the specific context for this repo. What it does, how to build/test/run, project-specific gotchas.

Everything merges. Your global safety rules still apply when you're deep in a specific project. Write it once at the top, it cascades down to everything below.

---

4. Connecting to External Tools

Claude can talk to almost anything — your logging platform, issue tracker, databases, cloud services. The question is which connection method to use.

MCP Servers — Use These When Available

MCP (Model Context Protocol) is the native way to connect Claude to external services. Purpose-built: structured queries, built-in auth, Claude understands the tool's capabilities natively.

# Atlassian (Jira + Confluence)
claude mcp add --transport sse atlassian https://mcp.atlassian.com/v1/sse

# DataDog (logs, metrics, monitors)
claude mcp add datadog --scope user -- ~/.local/bin/datadog_mcp_cli

After connecting, Claude can search Jira, create tickets, query DataDog logs, browse Confluence — all through natural language. It respects your existing permissions.

A word of caution: Every MCP server you connect eats into your context window. Each one injects its tool definitions into every request, even if you're not using it in that session. Connect five MCP servers and you've burned a chunk of your context before you've even typed anything. Be deliberate — only enable the ones you actually use regularly. You can check per-server context cost with /mcp.

Where to configure:

• ~/.claude/mcp.json — personal tools, all projects
• .mcp.json in project root — project-specific, can be checked into git for the team

CLI Tools — The Easy Fallback

No MCP server? If the tool has a CLI, Claude can run it directly. Install it, and Claude figures out the flags.

# GitHub CLI
> List all open PRs that need my review

# AWS CLI
> Show me the last 50 lines from the camel-service CloudWatch log group

# Azure CLI
> Query our ADX cluster for failed exports since yesterday

REST APIs — The Universal Backup

Anything with an API is fair game. Give Claude the endpoint, method, and auth. More setup, but works for everything.

How to Choose

Does an MCP server exist for your tool?
  └─ Yes → Use it. Best experience, least friction.
  └─ No → Does the tool have a CLI?
           └─ Yes → Install it, Claude will use it via bash.
           └─ No → Find the API docs and give Claude the endpoint + auth.

Claude can also work with databases (direct queries), SSH connections, SDKs, and local files — essentially anything accessible from your terminal.

---

5. Search Your Logs

Now that you know how to connect tools, try it. Start with something read-only — connect Claude to your logging service and search for errors. You'll get immediate value and can't break anything.

Step 1: How Can Claude Access Your Logs?

Before jumping in, think about this: how would you access your logs right now? That tells you how Claude can too.

• Do you log into a web UI? (DataDog, Splunk, Kibana, CloudWatch) → Check if there's an MCP server or API
• Do you use a CLI tool? → Claude can run it directly
• Do you SSH into a box and tail log files? → Claude can SSH too
• Do you run queries against a data store? (ADX, Elasticsearch, BigQuery) → Claude can build and run queries
• Are logs written to files on disk? → Claude can read them directly

The answer shapes your approach. Start with whatever's easiest — you can always upgrade to a better connection later.

Step 2: Connect and Search

If your tool has an MCP server (DataDog, Atlassian, etc.):

# DataDog example
claude mcp add datadog --scope user -- ~/.local/bin/datadog_mcp_cli

# Then just ask
> Show me all errors from the inventory-sync service in the last hour

If your tool has a CLI:

# Claude can run any CLI tool you have installed
> Use the az CLI to query our ADX cluster for failed order exports in the last 24 hours

If your tool has an API:

> Hit the logging API at https://logs.example.com/api/v1/search
> Auth header: Bearer <token>
> Find all 500 errors in the last 4 hours

If you have log files on disk:

> Read /var/log/app/camel-integration.log and find any exceptions from today

The point: however your logging is accessible, Claude can use it. Try it. When the results aren't what you expected, refine your prompt and try again — that's the core skill you're building.

---

6. Teaching Claude Your Workflow

This is the section that separates "using AI to autocomplete code" from "having an AI that works the way your team works."

Most developers set up CLAUDE.md with their tech stack and stop there. The real power is encoding your process. When Claude knows your workflow, it doesn't just write code — it follows your team's rules without you having to enforce them manually.

Before: No Workflow Encoded

You:  Add a retry mechanism to the Cirro export

Claude: [writes code, commits directly to main]
        Done! I've added exponential backoff retry logic.

No ticket. No branch. No tests. No PR. You now have to undo this and redo it properly.

After: Workflow in CLAUDE.md

With your workflow encoded:

You:  Add a retry mechanism to the Cirro export

Claude: I don't see a Jira ticket for this. Should I create one?
        Suggested: "Add retry mechanism to Cirro order export"
        Project: CAMEL, Type: Story

You:  Yes, do it.

Claude: Created CAMEL-847. I'll branch off develop as
        feature/CAMEL-847-cirro-export-retry.
        [writes code, writes tests, runs tests]
        All 3 new tests pass, existing tests pass.
        Ready to commit and open a PR?

You:  Go for it.

Claude: PR #142 created with description, test plan, and link to CAMEL-847.
        Assigned for LLM review before human review per your workflow.

Same request. Completely different outcome. The only difference is what's in CLAUDE.md.

What to Encode

Think about every step between "I have an idea" and "it's in production." Write each one down:

• Ticketing: Does every change need a ticket? What project? What fields?
• Branching: What's your naming convention? Where do you branch from?
• Testing: What's the minimum test coverage? Integration tests required?
• Documentation: Do new features need doc updates? Where do docs live?
• Code review: Does it go through an LLM review first? Who reviews?
• Deployment: Staging first? Manual approval? Specific deploy commands?
• Commit messages: Conventional commits? Ticket reference required?

The more of your process Claude knows, the less you have to micromanage.

---

7. Document Your Service

Time to put it all together. You're going to use Claude to create a ticket, write documentation, and submit a PR — the full workflow loop.

The Task

Pick something you know well — a service you own, an integration you built, a process you follow. It doesn't have to be code-related. It could be as simple as how to make a cup of coffee. The point is to practice using Claude to create documentation.

Requirements:

1. Create a GitHub issue in the pop-docs repo
2. Write a doc that includes a Mermaid sequence diagram
3. Drop it in docs/exercises/
4. PR it back

Check out the example doc to see what a finished exercise looks like.

But Wait — How Is Claude Going to Access GitHub?

Good instinct. You just met this thing and now it wants push access to your repos? No thanks.

The answer: you don't give it the keys to the kingdom. You give it a scoped token — locked to one repo, with only the permissions it needs, and an expiration date. Claude uses gh (the GitHub CLI) under the hood, so you just auth that CLI with a restricted token and Claude inherits exactly the access you defined. Nothing more.

Step 0: Create a Scoped GitHub Token

Here's how to set that up. This is good practice for any AI tool — never give it more access than it needs.

1. Go to GitHub → Settings → Developer Settings → Fine-grained tokens
2. Token name: claude-pop-docs (or whatever)
3. Expiration: 7 days (you won't need it after the exercise)
4. Repository access: Select "Only select repositories" → choose PopSockets/pop-docs
5. Permissions (under Repository permissions):
6. Contents: Read and write
7. Issues: Read and write
8. Pull requests: Read and write
9. Everything else: No access
10. Click Generate token and copy it

Now configure the GitHub CLI with your scoped token:

echo "<your-token>" | gh auth login --with-token

Claude uses gh under the hood for GitHub operations, so this is all it needs. When you're done with the exercise, revoke the token from the same settings page.

This is a real skill — scoping credentials for AI tools is something you'll do for every service you connect. Start with the minimum access and expand only if needed.

Step 1: Clone and Initialize

First, clone the docs repo and let Claude orient itself:

# Clone the repo
gh repo clone PopSockets/pop-docs
cd pop-docs

# Let Claude scan the project and generate a CLAUDE.md
claude init

Claude scans the project structure, reads existing docs, and generates a CLAUDE.md with sensible defaults. Review it, tweak anything that's off, commit it.

Step 2: Start a Session

Now start Claude inside the repo:

claude

You're in a session with full project context. Everything from here happens inside the conversation.

Step 3: Create a Ticket

> Create a GitHub issue in this repo — I'm going to document
  [your topic]. Title it "[Your Name] - [Topic] Documentation"

Step 4: Write the Doc

> Branch off that issue and create a doc at
  docs/exercises/[your-topic].md
  Include a description of the process and a Mermaid sequence
  diagram showing the flow.

Claude will draft it, but you'll need to iterate. Correct what's wrong, add detail, refine the diagram. That's the skill.

Step 5: PR It Back

> Commit this, push it, and open a PR back to main.
  Link the GitHub issue.

Why This Exercise

You just practiced the full AI workflow: - Tool connection — Claude talked to GitHub (issues, branches, PRs) - Content creation — Claude drafted documentation with your guidance - Mermaid diagrams — rendered natively in the docs site - Workflow execution — ticket → branch → work → PR - Iteration — you corrected Claude and it adapted

And as a bonus, pop-docs now has your contribution that the team can see.

---

8. Skills and Plugins

Claude Code supports skills — specialized capabilities that extend what Claude can do. Think of them as expert modes you can activate for specific tasks.

Superpowers

A collection of workflow skills that enforce engineering discipline:

Skill	What It Does
writing-plans	Creates structured implementation plans before you touch code
systematic-debugging	Forces methodical debugging instead of guess-and-check
test-driven-development	Writes tests first, then implementation
requesting-code-review	Reviews your work against requirements before you submit
verification-before-completion	Runs verification and confirms output before claiming "done"
brainstorming	Explores approaches and design decisions before jumping to code

These are guardrails. They slow Claude down in the right places — planning before coding, testing before shipping, verifying before claiming success.

Compound Engineering

Specialized review and research agents that run as sub-processes:

Skill	What It Does
code-reviewer	Multi-agent code review against your plan and standards
security-sentinel	Security audit — OWASP, input validation, auth, hardcoded secrets
performance-oracle	Performance analysis — bottlenecks, complexity, queries, memory
architecture-strategist	Architectural review — pattern compliance, design integrity
pattern-recognition-specialist	Finds anti-patterns, naming inconsistencies, duplication
framework-docs-researcher	Pulls live documentation for any library or framework

Live Documentation Lookup (Context7)

Ever had Claude confidently write code using an API method that doesn't exist? This plugin fixes that. It fetches the actual current documentation for any library directly into your session before Claude writes code. No more hallucinated API signatures — Claude checks the real docs first.

Installing Skills

Skills are plugins installed from inside a Claude session using /install-plugin:

> /install-plugin superpowers

Claude will find it in the official plugin marketplace and install it. Same process for any plugin. Context7 is an MCP server — install it separately:

claude mcp add context7 --scope user -- npx -y @upstash/context7-mcp@latest

After installing plugins, restart Claude and they're active.

Using Skills

Skills activate automatically when relevant, or you can invoke them explicitly:

> /review — run a code review on the current changes
> /commit — commit with a well-structured message
> /plan — create an implementation plan before coding

---

9. Context, Memory, and Sessions

Claude doesn't have unlimited memory. Understanding how it works prevents frustration.

The Context Window

Every session has a finite context window. It fills up with conversation history, file contents, tool outputs, and CLAUDE.md instructions. When it gets full, Claude compacts — summarizing older parts of the conversation and clearing stale tool outputs to make room.

What survives compaction:

• CLAUDE.md files — reloaded fresh from disk every time
• Key decisions and code changes
• The gist of what you've been working on

What gets lost:

• Detailed tool outputs from earlier in the session
• Instructions given only in conversation (not in CLAUDE.md)
• Nuance from early discussions

The rule: If something is important enough that you'd be annoyed if Claude forgot it, put it in CLAUDE.md. Conversation is ephemeral. Files are permanent.

Permanent Memory

Claude has persistent memory that survives across sessions:

What	Where	Purpose
Global CLAUDE.md	~/.claude/CLAUDE.md	Your personal defaults, all projects
Project CLAUDE.md	./CLAUDE.md	Project instructions, shared via git
Rules	.claude/rules/*.md	Topic-specific rules (security.md, testing.md)
Auto-memory	~/.claude/projects/<project>/memory/	Things Claude learns and notes for itself

Auto-memory is Claude's personal notebook. When it discovers something — a gotcha, a convention, a credential location — it writes it down. Next session, it reads those notes and starts smarter.

Sessions

Sessions are stored locally and can be resumed:

claude --continue            # Resume most recent session
claude --resume              # Pick from a list
claude --resume "api-fix"    # Resume by name

When to start fresh vs. continue:

• Continue when you got interrupted and want to pick up the same task
• Start fresh when the old session has been running long — context degradation makes a new session more effective than a compacted old one
• Start fresh when switching to a completely different task

Sessions live on your machine. They don't sync between devices. Your CLAUDE.md files do (if they're in git).

---

10. How to Talk to Claude Effectively

This is the actual skill. The tool is only as good as what you give it.

State the Goal, Not the Steps

Bad:   Open the file OrderExportService.java, go to line 47,
       add a null check for shippingMethod, save the file

Good:  The order export fails with a 500 when shipping method is null.
       Add null handling with a sensible default.

Let Claude figure out the approach. You define what, Claude figures out how.

Provide Context About Why

Weak:  Add logging to the retry handler

Better: Add logging to the retry handler — we're seeing silent failures
        in production where exports fail 3 times and we never know about
        it until Cirro reports missing orders

The "why" helps Claude make better decisions about what to log, where to log it, and at what level.

Be Specific When It Matters

Vague:   Fix the tests

Specific: The Cirro inventory sync test at InventorySyncTest.java:89 is
          failing because it expects JSONL format but we're sending raw
          JSON. Update the test to match the new format.

Specificity matters most for bug reports and targeted changes. For exploration and architecture questions, be vaguer and let Claude investigate.

Course-Correct Early

If Claude starts going in the wrong direction, don't let it finish. Interrupt:

> Stop — that's the wrong approach. We don't use that pattern here.
  Instead, we handle this at the controller level. Try again.

Claude learns from corrections within the session. The earlier you redirect, the less time wasted.

Iterate, Don't Over-Specify

Don't try to write the perfect prompt. Start simple, review the result, refine:

You:    Add retry logic to the Cirro export
Claude: [writes basic retry]
You:    Good start but we need exponential backoff, max 3 retries,
        and it should log each attempt
Claude: [refines]
You:    Add a circuit breaker that stops retrying after 5 consecutive
        failures across different orders
Claude: [adds circuit breaker]

Three simple prompts beats one massive over-specified prompt every time.

---

11. Honest Limitations

AI tooling has real limitations. Knowing them prevents frustration and bad outcomes.

Hallucination

Claude will occasionally reference APIs, methods, or configurations that don't exist. It's confident when it does this. Always verify:

• API signatures against actual docs
• Configuration options against actual config files
• Third-party library behavior against the library's source

The context7 skill helps here — it pulls real, current documentation instead of relying on Claude's training data.

Context Degradation

Long sessions get worse over time. As the context window fills and compacts, Claude loses detail from earlier in the conversation. Signs it's happening:

• Claude asks about something you already discussed
• It contradicts an earlier decision
• Responses get less specific

Fix: Start a fresh session. Put important decisions in CLAUDE.md so they survive.

Blind Trust

Claude writes plausible-looking code. That doesn't mean it's correct. Review diffs the same way you'd review a junior developer's PR:

• Does this actually solve the problem?
• Are there edge cases it missed?
• Does it match your project's patterns and conventions?
• Did it introduce any security issues?

"Claude wrote it" is not a substitute for code review.

When NOT to Use It

• Sensitive credential handling — don't paste production secrets into the conversation
• Complex algorithmic work where you need to reason through the logic yourself
• When you'd spend more time explaining the context than doing it yourself
• Performance-critical code that needs benchmarking and profiling, not just writing

---

12. Security and Credentials

Before connecting Claude to your team's systems, understand the data flow.

What's Safe

• Connecting to tools via MCP servers (auth is handled by the MCP layer)
• Using CLI tools that manage their own credentials (e.g., gh auth login)
• Reading code, logs, and documentation
• Environment variables for API keys (Claude can read them but they stay local)

Credential Files — The Safe Way to Store Secrets

Claude can manage its own credentials in a file that lives outside your repo — in its project memory directory:

~/.claude/projects/<project-path>/memory/credentials.md

This file never touches your repo, never gets committed, and Claude reads it automatically at the start of every session. When you need to give Claude an API key, a database connection string, or a token, tell it to save the credential there instead of pasting it into the chat or CLAUDE.md.

The scoping matters:

• Global credentials (GitHub token, personal API keys) → store in your root-level memory: ~/.claude/memory/credentials.md
• Project credentials (staging DB, project-specific API keys) → store in the project memory: ~/.claude/projects/<project>/memory/credentials.md

Claude picks up the right credentials based on which directory you're working in. A GitHub token stored globally is available everywhere. A staging database password stored in the camel project's memory is only available when you're working in that project.

To set it up, just tell Claude:

> Save these credentials to your credential file:
  Staging DB: postgresql://readonly:pass@staging.example.com:5432/orders
  Cirro API key: sk-cirro-abc123

Claude writes the file in the right place. You never have to think about the path.

What to Be Careful About

• Don't put secrets in CLAUDE.md — it gets committed to git. Use credential files (above) or environment variables instead.
• Don't paste production database credentials into the chat — use a read-only connection or a staging environment.
• Be cautious with production access — Claude can run any command you allow. If it has production SSH access, it can do production damage. Scope access to what's necessary.
• API tokens — use scoped tokens with minimum required permissions. Don't give Claude your admin token when a read-only token works.

Team Considerations

• CLAUDE.md in git — treat it like any other shared config. PR changes, review updates. Don't put personal preferences in the project-level file.
• Shared .mcp.json — check project-level MCP configs into git so the whole team gets the same tool connections.
• Personal configs — use ~/.claude/CLAUDE.md and ~/.claude/mcp.json for individual preferences and personal tool connections.

---

13. Tips

• claude --continue — resumes your last conversation with full context. Use it when you get interrupted.
• Turn off bash confirmations — once you trust your setup, go to /config and auto-allow bash commands. Eliminates the approval prompt on every shell command.
• Let Claude read first — don't describe code to Claude. Point it at the file and let it read. It's faster and more accurate than your summary.
• Have Claude spin up gists — anything gross to copy-paste in the terminal (long JSON payloads, multi-line commands), have Claude create a gist and give you the link.
• Use parallel agents — for independent tasks, Claude can kick off multiple agents that work simultaneously.
• /compact manually — if a session feels sluggish or Claude is losing context, manually compact to free up space.