How these lessons work
Every project here is small, real, and something you'd actually use. The first is the pattern from Integrate: a known input, a prompt, a known output shape, and a model in the middle. The second hands the model tools and lets it decide the steps. Between them they cover most of what gets built with AI.
Project 1: an AI release-notes generator
What you'll build: a command-line tool that reads your git commits since the last release and turns them into clean, grouped, human-readable release notes. ~45 lines.
Step 1 — Set up
mkdir release-notes && cd release-notes
npm init -y
npm install @anthropic-ai/sdk
npm install -D typescript @types/node tsx
npx tsc --initAdd "type": "module" to package.json, and set your key in the shell: export ANTHROPIC_API_KEY=sk-ant-...
Step 2 — Collect the commits
Git already has the raw material. Grab every commit subject since the most recent tag (or the whole history if there are no tags yet).
// release-notes.ts
import { execSync } from "node:child_process";
function getCommits(): string {
let range = "";
try {
const lastTag = execSync("git describe --tags --abbrev=0")
.toString()
.trim();
range = `${lastTag}..HEAD`;
} catch {
// No tags yet — use the whole history.
}
return execSync(`git log ${range} --pretty=format:"- %s"`)
.toString()
.trim();
}Step 3 — Hand it to the model
The commits are messy and developer-facing. The model's job is to rewrite them as something a user would want to read. All the intelligence lives in the system prompt.
import Anthropic from "@anthropic-ai/sdk";
async function main() {
const commits = getCommits();
if (!commits) {
console.error("No commits since the last tag.");
process.exit(0);
}
const client = new Anthropic(); // reads ANTHROPIC_API_KEY
const res = await client.messages.create({
model: "claude-opus-5-5",
max_tokens: 16000,
system:
"You turn raw git commit messages into clean release notes. " +
"Group them under headings (Features, Fixes, Other). Rewrite " +
"each line to be clear and user-facing. Drop noise like 'wip' " +
"or 'fix typo'. Output Markdown only, no preamble.",
messages: [{ role: "user", content: commits }],
});
if (res.stop_reason !== "end_turn") {
// Cut off by the length limit, or the request was declined.
console.error(`Incomplete answer (${res.stop_reason}).`);
process.exit(1);
}
for (const block of res.content) {
if (block.type === "text") console.log(block.text);
}
}
main().catch((err) => {
console.error(err);
process.exit(1);
});Step 4 — Run it
npx tsx release-notes.tsFrom inside any git repo, you get back tidy Markdown release notes grouped into Features / Fixes / Other. That is a real AI feature — input, prompt, output — in about 45 lines.
Step 5 — Make it yours
- Write the notes to
CHANGELOG.mdinstead of stdout. - Pass the commit body too (
%s%n%b) so the model has more context. - Use structured output to get typed data (version, date, sections) and render the Markdown yourself — see Integrate.
- Release notes don't need the flagship. Try a cheaper model and compare the output — see the AI Picker.
- Wire it into a release script or CI step.
Project 2: an agent that answers questions about your code
The release-notes tool makes one call: text in, text out. This one is an agent. You give it a question about a codebase; it decides what to search for, reads the files it finds, and keeps going until it can answer. You write two tools and a brief — the SDK runs the loop.
Step 1 — Set up
mkdir repo-agent && cd repo-agent
npm init -y
npm pkg set type=module
npm install @anthropic-ai/sdk zod tsxStep 2 — Write the tools
A tool is a name, a description the model reads to decide when to use it, a schema for its arguments, and a function. These two are read-only on purpose: the worst this agent can do is read a file in the folder you ran it in.
// repo-agent.ts — answers a question about the code in this folder.
import Anthropic from "@anthropic-ai/sdk";
import { betaZodTool } from "@anthropic-ai/sdk/helpers/beta/zod";
import { z } from "zod";
import { execFileSync } from "node:child_process";
import { readFileSync } from "node:fs";
import path from "node:path";
const root = process.cwd();
// Refuse any path that climbs out of the project folder.
function inside(file: string): string {
const full = path.resolve(root, file);
if (full !== root && !full.startsWith(root + path.sep)) {
throw new Error("That path is outside the project.");
}
return full;
}
const searchCode = betaZodTool({
name: "search_code",
description:
"Search the project's tracked files for a word or phrase. Returns matching lines with file names and line numbers. Use this first to find where something lives.",
inputSchema: z.object({ text: z.string().describe("Text to look for") }),
run: async ({ text }) => {
try {
const out = execFileSync("git", ["grep", "-n", "-I", "-F", "-e", text], {
cwd: root,
maxBuffer: 10_000_000,
}).toString();
return out.split("\n").slice(0, 60).join("\n");
} catch {
return "No matches.";
}
},
});
const readFile = betaZodTool({
name: "read_file",
description:
"Read one file from the project. Use it after search_code to see the code around a match.",
inputSchema: z.object({ file: z.string().describe("Path relative to the project root") }),
run: async ({ file }) => {
try {
return readFileSync(inside(file), "utf8").slice(0, 20_000);
} catch (err) {
return `Could not read ${file}: ${(err as Error).message}`;
}
},
});Step 3 — Give it the question and let it loop
const question = process.argv.slice(2).join(" ");
if (!question) {
console.error('Usage: npx tsx repo-agent.ts "where is the login handled?"');
process.exit(1);
}
const client = new Anthropic(); // reads ANTHROPIC_API_KEY
const final = await client.beta.messages.toolRunner({
model: "claude-opus-5-5",
max_tokens: 16000,
max_iterations: 15, // a confused agent stops here instead of running up a bill
system:
"You answer questions about the code in this project. Look things up with " +
"your tools before answering; do not answer from memory. Name the files " +
"and line numbers your answer rests on. If you cannot find it, say so.",
tools: [searchCode, readFile],
messages: [{ role: "user", content: question }],
});
for (const block of final.content) {
if (block.type === "text") console.log(block.text);
}Step 4 — Run it
From inside any git repository:
npx tsx /path/to/repo-agent.ts "where do we validate email addresses?"Behind that one call the model searched, read a file or two, perhaps searched again with a better word, and then answered with file names and line numbers. You never told it which steps to take.
Step 5 — Make it yours
- Add a
list_filestool so it can explore a project it has never seen. - Add a
git_logtool and ask it why a line changed. - Turn the two tools into anMCP server, and every agent you use gets them.
More projects to try
Same patterns, new task. Each of these is a weekend-sized build:
PR review helper
A script that takes a git diff and returns a first-pass review: risks, edge cases, missing tests. Same shape — input, prompt, output.
Docs Q&A tool
Point it at a folder of Markdown, ask a question, get an answer with the source file cited. Your first taste of retrieval.
Your own MCP tool
Wrap one thing you do by hand — look up an order, query a log — as a tool your coding agent can call. The step from using AI to extending it.
Commit-message writer
Stage your changes, run the tool, get a clear conventional commit message from the diff. Tiny, and you'll use it daily.
You now have two things that work on the examples you tried. Whether they work in general — and whether a cheaper model would do — is the next step: Evals.