What should a software engineer put in a brag document?

What you shipped and the problem it solved, decisions you made and why, work that didn't ship, incidents you fixed, and people you helped. Add a number only where you can point to where it came from.

How often should I update a brag document?

Julia Evans, in her 2019 post on brag documents, says many people have told her a few minutes every two weeks works best. She does one long session every six months or every year. Either works if you have a record to fill it from.

How do I paste a Markdown template into Google Docs?

Turn on Tools > Preferences > Enable Markdown, then right-click in the document and choose Paste from Markdown.

Can AI fill in my brag document?

It can draft what you did from your commits and your Claude Code prompts. Tell it never to invent numbers, and write why the work mattered yourself.

What's a good brag document template for engineers?

A brag document is a list of what you did at work and why it mattered. You give it to your manager before reviews, so they can argue for you with real examples instead of whatever they happen to remember.

Julia Evans wrote about brag documents in 2019. Her reason, from Get your work recognized: write a brag document: "if you don't remember everything important you did, your manager (no matter how great they are!) probably doesn't either."

Brag document template in Markdown

# Brag document: [Your name], [Period, e.g. Q3 2026]

## Goals for this period
- [What you and your manager agreed mattered most]

## Shipped
### [Project or feature name]
- What: [One or two sentences on what you built]
- Problem it solved: [What was wrong before, and for whom]
- Impact: [A number you can point to: users, latency, incidents, time saved]
- Evidence: [PR links, dashboards, the doc or thread where it was discussed]

## Decisions
- [A tradeoff you made: "Chose X over Y because Z"]

## Work that didn't ship
- [Investigations, prototypes you killed, approaches you ruled out, and what the team learned]

## Helping others
- [Code reviews, mentoring, docs, onboarding, unblocking someone]

## Incidents and fixes
- [What broke, what you did, what changed so it won't happen again]

## What I learned
- [Skills, tools, parts of the system]

## Next period
- [What you want to take on, and what support you need]

Paste it into Google Docs or Notion

To get real headings and lists in Google Docs:

Go to Tools > Preferences and tick Enable Markdown.
Right-click in the document and choose Paste from Markdown (Google's help page).

For Notion, save the template as brag.md, then go to Settings > Import > Text & Markdown and upload it (Notion's import guide). Obsidian, or any editor that opens .md files, takes it as is.

What to write in each section

Put the problem next to the thing you built. "Built the webhook retry queue" is a task. "Built a retry queue because payment webhooks failed on timeouts and never retried" tells your manager why it mattered.

Only write numbers you can point to. Your manager may repeat one in a meeting you're not in, so until you've looked it up, leave a gap like [add impact: failed payment webhooks per week, before and after].

Don't skip the decisions section. "Chose Postgres over DynamoDB because the reports needed joins" shows why you picked it. The commit only shows that you did.

Work that didn't ship counts too. A week spent ruling out three approaches is real work, but none of it shows up in git.

People often leave out work like refactoring or making on-call easier, because it's hard to explain why it mattered. Evans calls this "fuzzy work". Her fix: write the goal, what you did toward it, and any effect you've seen, even an indirect one.

Draft it from Claude Code history and git log

Evans says many people have told her a few minutes every two weeks works best. For her, it's "a single marathon session every 6 months or every year."

Either way, the hard part is remembering. If you use Claude Code, a lot of it is already written down. Every prompt you've typed in the terminal is in ~/.claude/history.jsonl, with a timestamp and the project folder, and Claude Code keeps that file until you delete it. The full conversations, with Claude's replies, are in ~/.claude/projects/, but those get deleted after 30 days by default (Claude Code docs). (Since v2.1.248, sessions you last used in Claude Desktop or Cowork are kept at any age, unless you or your company set a limit.)

Three steps, and you have a brag doc at review time:

Paste this into Claude Code, change the dates to your review period, and paste the template underneath:

Fill in my brag document for July 1 to September 30, 2026, using the template at the end of this message.

1. ~/.claude/history.jsonl has one JSON object per line for every prompt I've typed into Claude Code in the terminal: "display" is the prompt, "timestamp" is in milliseconds, "project" is the folder. It's a big file, so write a short script that keeps only the lines in my date range instead of reading all of it.
2. The full conversations, with your replies, are in ~/.claude/projects/: one .jsonl file per session, one JSON object per line, with "timestamp" (an ISO date), "cwd" (the project folder), "type" ("user" or "assistant") and "message". Files older than 30 days may already be gone. For the ones in my date range, write a script that keeps only the user and assistant text, and use it to work out what each piece of work was and what problem it solved.
3. For each project folder in the history.jsonl lines that is a git repo, run: git -C <folder> log --since=2026-07-01 --until="2026-09-30 23:59" --author="$(git config user.name)" --oneline
4. If the gh CLI is installed and logged in, get my username with gh api user --jq .login, then list the pull requests I reviewed with gh search prs --reviewed-by=<username> --updated=2026-07-01..2026-09-30. Put them under "Helping others".
5. Group the prompts, conversations and commits into pieces of work, most significant first. For each one, say what I built and the problem it solved, only where my prompts, conversations or commits show it, and list its commits as evidence. Work with no commit goes under "Work that didn't ship".

Never invent numbers, users or outcomes. Where a number would help, write [add impact: what number] instead. Plain words, no hype.

[paste the template here]

Fill the [add impact: ...] gaps with real numbers, and cut any claim you can't back up. Why the work mattered is yours to write.
Once, today, open ~/.claude/settings.json and add "cleanupPeriodDays": 3650 inside the outer braces, with a comma after the line before it. Claude Code then keeps the full conversations for ten years instead of 30 days, so next review, step 2 of the prompt covers the whole period and not just the last month (settings reference). If the file is new or empty, this is the whole file:
```
{
  "cleanupPeriodDays": 3650
}
```

This only sees work that went through Claude Code, git and GitHub. Incidents you handled in Slack, mentoring and meetings won't be in any of them, so add those to "Incidents and fixes" and "Helping others" yourself.

For a slower walkthrough, with a script that prints one quarter of prompts so you can read them first, see how to write a brag doc from your Claude Code history.

Shabash, the Mac app I'm building, drafts brag docs from your Claude Code sessions and commits, for the period and projects you pick. Each claim in the draft has a small number; hover it to see the session, commit or piece of work behind it.