Most Claude Code tutorials stop at "here's how to install it." That's like teaching someone to drive by showing them the ignition. This Claude Code tutorial goes further — you'll use it to build a real AI-powered app from scratch and deploy it to production, step by step.
By the end you'll have a working document Q&A API and a live deployment URL. The whole thing takes about an afternoon.
What Claude Code actually is (and why it's different)
Claude Code is Anthropic's AI coding agent that runs in your terminal. Unlike copilot-style tools that suggest individual lines inside an editor, Claude Code operates at the project level — it reads your entire codebase, understands how files relate to each other, and makes multi-file changes with full context.
The practical difference: you describe what you want to build, and Claude Code writes the code, runs commands, fixes errors, and iterates — without you switching between a chat window and your editor. It's AI-augmented development where the AI is a collaborator in your actual workflow, not a suggestion box beside it.
What makes it powerful for AI app development specifically:
- It can generate boilerplate for FastAPI, Express, or any framework in seconds
- It writes tests alongside the code it generates
- It catches its own mistakes by running the code and reading error output
- It handles the tedious parts (CI config, requirements.txt, test scaffolding) while you focus on the actual problem
Getting started: install and configure Claude Code
Install
npm install -g @anthropic-ai/claude-code
Requires Node.js 18+. Verify:
claude --version
Authenticate
claude
On first run, Claude Code opens a browser window to authenticate with your Anthropic account. Once authenticated, it drops you into an interactive session in your current directory.
Your first command
Navigate to an empty project folder and try:
mkdir my-ai-app && cd my-ai-app
claude
In the Claude Code prompt:
> Scaffold a FastAPI project with a single /health endpoint, a requirements.txt, and a .gitignore
Claude Code will create the files, show you what it's doing, and confirm. This is the core interaction pattern: describe the outcome, let it execute.
Build a real AI app with Claude Code
We're building a document Q&A API — you upload a text document, ask questions about it, and get answers grounded in the document's content. It's a practical RAG (retrieval-augmented generation) pattern used in real products.
Step 1 — Scaffold the project
In your Claude Code session:
> Create a FastAPI app for document Q&A. The app should:
> - Accept a POST /upload endpoint that takes a text file and stores it in memory
> - Accept a POST /ask endpoint that takes a document_id and a question, then answers using OpenAI gpt-4o-mini
> - Return answers in JSON with the answer text and a confidence field
> - Include a requirements.txt with fastapi, uvicorn, openai, and python-multipart
Claude Code will generate the full project structure:
my-ai-app/
├── main.py
├── requirements.txt
├── .gitignore
└── README.md
It writes the entire main.py — endpoints, in-memory document store, OpenAI call — in one pass.
Step 2 — Run it and fix errors
> Run the app locally with uvicorn and show me any errors
Claude Code executes uvicorn main:app --reload, reads the output, and if there are import errors or missing packages it fixes them automatically. This loop — run, read error, fix — is where Claude Code earns its keep. You don't context-switch; it just handles it.
Step 3 — Add real retrieval (not just stuffing the whole document)
The naive version sends the entire document to the model on every question. That breaks on large files and wastes tokens. Ask Claude Code to improve it:
> The current /ask endpoint sends the full document to OpenAI on every request.
> Refactor it to:
> - Split documents into 500-token chunks on upload
> - Use cosine similarity on TF-IDF vectors to find the top 3 relevant chunks
> - Only send those 3 chunks to OpenAI as context
> - Use numpy and sklearn for the vector operations
This is multi-file, multi-concept work. Claude Code will update main.py, add sklearn and numpy to requirements.txt, and implement the chunking + retrieval logic coherently. It understands that changing the upload flow affects the query flow and handles both.
Step 4 — Write tests
> Write pytest tests for both endpoints. Include:
> - A test that uploads a sample document and verifies the document_id is returned
> - A test that uploads a document, then asks a question whose answer is clearly in the document
> - A test that asks about a document_id that doesn't exist and expects a 404
> Mock the OpenAI call so tests don't need a real API key
Claude Code generates test_main.py with the exact structure you described, uses pytest-mock for the OpenAI mock, and adds the test dependencies to requirements.txt.
Run them:
> Run the tests and fix any failures
Claude Code runs pytest, reads the output, and iterates until they pass. The critical detail: it doesn't just generate tests and hand them back — it runs them and closes the feedback loop.
The CLAUDE.md file: your project's AI instruction layer
One of the most underused Claude Code features is CLAUDE.md — a file in your project root that Claude Code reads at the start of every session. Think of it as a permanent briefing document for your AI collaborator.
Create one:
> Create a CLAUDE.md for this project that documents:
> - The tech stack (FastAPI, OpenAI, sklearn)
> - The coding conventions we used (snake_case, type hints everywhere, docstrings on public functions)
> - The test setup (pytest, mock OpenAI calls)
> - What the /upload and /ask endpoints do
From this point on, any new Claude Code session on this project starts with full context. You don't re-explain the stack every time.
A good CLAUDE.md includes:
# Project: Document Q&A API
## Stack
- FastAPI + Uvicorn (Python 3.11)
- OpenAI gpt-4o-mini for generation
- sklearn TF-IDF + cosine similarity for retrieval
- pytest + pytest-mock for testing
## Conventions
- Type hints on all function signatures
- Snake_case everywhere
- Docstrings on all public functions
## Architecture
- Documents stored in-memory (dict keyed by UUID)
- Chunks: 500 tokens, 50-token overlap
- Top 3 chunks retrieved per query
## Running locally
uvicorn main:app --reload --port 8000
## Running tests
pytest -v
Deploy to production with the NEXUS AI CLI
Your app is built and tested. Now get it live — no Dockerfile required.
NEXUS AI detects your framework, builds the container for you, and deploys it. You push source code; NEXUS AI handles everything from there.
Step 5 — Push source to GitHub
Initialize a repo and push:
git init
git add .
git commit -m "initial: document Q&A API"
gh repo create my-ai-app --public --source=. --push
Or push to an existing repo. The only requirement is that your requirements.txt is at the project root — NEXUS AI uses it to detect that this is a Python app.
Step 6 — Install the NEXUS AI CLI
# Linux
curl -fsSL https://nexusai.run/install.sh | bash
# macOS
curl -fsSL https://nexusai.run/install-mac.sh | bash
Verify:
nexus --version
Step 7 — Deploy from source
# Log in to NEXUS AI
nexus auth login
# Deploy directly from your GitHub repo — no Docker required
nexus deploy source \
--repo https://github.com/your-org/my-ai-app \
--name doc-qa-api \
--port 8000 \
--provider gcp_cloud_run
# Add the OpenAI key as an encrypted secret
nexus secret create OPENAI_API_KEY --deployment doc-qa-api
# Attach a custom domain
nexus domain add api.yourcompany.com --deployment doc-qa-api
NEXUS AI clones your repo, detects the Python/FastAPI framework, builds a production container image, and deploys it. Within 2–3 minutes you have a live URL with TLS and autoscaling. Stream logs to verify:
nexus deploy logs doc-qa-api --follow
Automate deploys with GitHub Actions
Ask Claude Code to write the CI/CD config:
> Write a GitHub Actions workflow that redeploys the NEXUS AI deployment on every push to main.
> Use NEXUSAI_TOKEN as a secret. The deployment name is doc-qa-api.
Claude Code generates a complete .github/workflows/deploy.yml. The workflow calls nexus deploy redeploy doc-qa-api — NEXUS AI pulls the latest source, rebuilds the container, and rolls it out. Every push to main goes to production automatically.
Advanced Claude Code patterns for AI development
Multi-file refactoring
Claude Code handles refactors that would take hours manually. Example:
> The document store is currently an in-memory dict. Refactor it to use Redis so documents
> persist across server restarts. Update all references, add redis to requirements.txt,
> and update the CLAUDE.md architecture section.
It updates main.py, requirements.txt, and CLAUDE.md in one coherent pass — and since NEXUS AI builds from source, you just push the changes and redeploy.
Debugging without context-switching
When something breaks in production:
nexus deploy logs doc-qa-api --tail 50
Copy the error, paste it into Claude Code:
> Getting this error in production logs: [paste error]
> Find the root cause and fix it.
Claude Code reads the relevant code, identifies the issue, and applies the fix — all without you manually tracing through stack traces.
Using Claude Code for code review
Before opening a PR:
> Review the changes in git diff HEAD~1 for:
> - Security issues (injection, hardcoded secrets, unsafe deserialization)
> - Missing input validation on the API endpoints
> - Performance issues in the chunking logic
Claude Code runs the diff and produces a structured review with specific line references.
Common Claude Code mistakes to avoid
Giving vague prompts. "Make this better" produces mediocre output. "Refactor the chunking function to reduce memory allocation by processing tokens in a streaming fashion instead of loading the full document" produces a specific, actionable change.
Not using CLAUDE.md. Without it, you re-explain your stack every session. Ten minutes setting it up saves hours over the life of a project.
Accepting the first output blindly. Claude Code is fast, not infallible. Run the tests after every significant change. When they fail, let Claude Code fix them — that feedback loop is what makes it reliable.
Letting it over-engineer. Claude Code will sometimes propose abstractions you don't need. If you asked for a simple endpoint and got a three-layer architecture with an abstract repository pattern, push back: "Simplify this — no abstraction layers, just the endpoint and direct database calls."
Not scoping the context. In very large codebases, claude in the root directory gives it the whole repo. For a focused change, navigate to the relevant subdirectory first. Smaller context = more precise output.
Frequently asked questions
Does Claude Code work with languages other than Python?
Yes. Claude Code works with any language — TypeScript, Go, Rust, Ruby, Java. The same patterns apply: scaffold with a prompt, run it, let Claude Code fix errors. The CLAUDE.md approach works especially well in polyglot repos where you need to document which parts use which language.
Is Claude Code safe to run on production codebases?
Claude Code asks for confirmation before writing files or running commands. You control what it executes. For sensitive production repos, review the proposed changes before confirming — Claude Code shows you a diff before applying it. Never give it credentials directly; use environment variables and secrets managers.
How is Claude Code different from GitHub Copilot?
Copilot autocompletes individual lines and functions inside an editor. Claude Code operates at the project level in the terminal — it understands the full codebase, can run code, read test output, and make coordinated multi-file changes. They're complementary: Copilot for keystroke-level suggestions, Claude Code for larger tasks.
Can I use Claude Code without an Anthropic account?
No. Claude Code requires an Anthropic API key or Claude.ai Pro/Max subscription. Usage via the API is billed based on token consumption. The claude.ai subscription tiers include a monthly usage allocation.
What's the best way to handle large codebases?
Use .claudeignore (same syntax as .gitignore) to exclude directories that aren't relevant to your current task — node_modules, dist, venv, build artifacts. This keeps Claude Code's context focused on what matters and reduces token usage.
What you built
Start to finish: a document Q&A API scaffolded by Claude Code, with chunked retrieval, pytest coverage, and a live deployment on NEXUS AI — all without writing a Dockerfile or touching a browser.
That's AI-augmented development in practice. Claude Code handled the scaffolding, boilerplate, tests, and debugging loop. You handled the architecture decisions and product requirements. The result ships faster and has better test coverage than the same work done manually.
The NEXUS AI CLI handles the deployment side of this workflow. Install it, run nexus auth login, and your next Claude Code-built app is one command away from production.
Top comments (0)