Build · Step 9 of 14

Projects

Reading about AI gets you only so far. Here are two complete projects, built end to end — a tool that makes one model call, then a small agent — and a few more to take on yourself.

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 --init

Add "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.ts

From 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.

Notice what the model did and didn't do. It handled the fuzzy part — judging, grouping, rewording. Your code handled the deterministic part — getting the commits and printing the result. That split is the whole craft.

Step 5 — Make it yours

  • Write the notes to CHANGELOG.md instead 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 tsx

Step 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.

Look at what kept this agent safe, because it is the pattern fromAgents in miniature:few tools, read-only,confined to one folder, anda cap on the number of steps. Add a tool that writes files or runs commands and every one of those decisions needs revisiting — Security explains why.

Step 5 — Make it yours

  • Add a list_files tool so it can explore a project it has never seen.
  • Add a git_log tool 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.