How to document AI-assisted engineering work for your career

An AI agent can leave you with a clean diff and a terrible career record.

You remember that the agent wrote a lot of the code. You remember reviewing a pull request. You might even remember that the migration shipped without drama.

Three months later, the useful details are gone:

What constraint made the migration necessary?
Which options did you consider?
What did you reject, and why?
Which part of the output did you change?
How did you verify that the result was safe?

“Used an AI agent to migrate the UI library” is an activity. It does not explain your engineering judgment.

When a coding agent helps with the implementation, the career evidence is the record around the code: the problem, the decisions, the agent’s contribution, your review, the verification, the trade-offs, and the change that remained after the work.

I learned this while working on a migration away from deprecated UI-library primitives. The implementation included repetitive code that an agent could help produce. The part I needed to own was the system-level decision about where those components belonged and how to move them without turning the migration into an unplanned redesign.

That is the case study in this article.

The agent is part of the implementation record

An agent’s output is one input to the work. It is not the whole accomplishment.

The useful distinction is simple:

the agent can contribute code, searches, inventories, and draft tests;
you own the constraints, decisions, review, verification, and result.

That does not mean hiding the agent’s contribution. It means describing it at the right level.

Compare these two records:

The second version gives a future reader something to evaluate. It says what changed, what I owned, what the agent contributed, and where I drew the boundary around the work.

It also avoids a claim I cannot support. I am not saying the migration made the team faster or eliminated bugs. I would need evidence for that.

Case study: moving deprecated UI primitives

The migration had a clear architectural shape.

The application contained UI components that looked shared but still lived under the application’s local UI directory. A design-system package existed as the better home for reusable primitives. The work happened in two steps:

Move the common primitives into the design-system package.
Migrate the remaining generic UI and remove the app-local shims.

The first step covered components such as alerts, avatars, badges, cards, checkboxes, collapsibles, empty states, popovers, skeletons, tables, and tabs. The follow-up moved the remaining generic pieces, including dialogs, dropdown menus, command interfaces, data tables, filters, items, multi-selects, and sheets.

The exact component list is useful because it makes the scope inspectable. “Migrated the UI library” is too broad. A reviewer can understand what moved when the record names the boundaries.

Start with the constraint

The first line of the evidence record should not be “the agent generated the components.” It should explain the engineering problem.

For this migration, the safe version is:

Shared UI code needed a package-level home, while the application still had local implementations and compatibility shims.

That sentence is deliberately plain. It does not expose a customer, product name, internal URL, or proprietary design decision. It still gives the reader enough context to understand why the work existed.

Then add the boundaries you actually had to respect. For example:

keep the existing callers working while ownership changed;
update imports consistently across the application;
avoid mixing a component-location migration with an unrelated visual redesign;
remove local shims only after their consumers had a valid package-level import.

These are the constraints that make a repository-wide move engineering work instead of a file copy. If one of them was not part of your situation, remove it. The record should describe the real boundary, not a more impressive one.

This is where what counts as an accomplishment for a software engineer helps. The component names are activity. The ownership change and the constraints are the beginning of the accomplishment.

Preserve the decision

The important decision was not which syntax the agent used. It was where reusable UI should live and how to sequence the move.

I would preserve it like this:

I chose to establish the design-system package as the shared home, migrate the common primitives first, then remove the remaining app-local shims once the consumers could use the package directly.

That decision has a useful trade-off. A staged move creates more intermediate work than a single large rewrite, but it makes the ownership boundary easier to inspect. It also separates a location and dependency change from a product redesign.

The rejected approaches belong in the record too:

letting the agent update files without first defining the destination package;
redesigning component behavior while changing component ownership;
keeping every local shim indefinitely because the application still compiled;
treating the number of changed lines as the outcome.

The first two would make review harder. The third would leave the old boundary in place. The fourth would confuse implementation size with engineering impact.

You do not need to preserve every abandoned idea. Save the alternatives that explain the decision you made and the risk you were managing.

Record what the agent actually contributed

“AI-assisted” is too vague to be useful by itself. Write down the part of the implementation the agent helped with.

That might include:

creating or adapting repetitive component files;
updating a known set of imports;
producing an inventory of remaining local wrappers;
drafting tests around existing behavior;
checking for references to the old path.

Use the narrowest accurate description. If the agent only drafted a component, say that. If it changed many files, keep the file set or component categories. If you cannot remember the exact prompt, do not invent one later.

An illustrative agent-output note could look like this:

Agent contribution:
Drafted package-level versions of the identified UI primitives and prepared the follow-up import changes.

My review:
Compared the exported names and props with the existing callers, removed changes that belonged to a visual redesign, and kept the package move separate from unrelated cleanup.

The label “illustrative” matters. Do not present a reconstructed summary as a transcript. Your source record should distinguish what you captured at the time from what you are explaining later.

The agent’s contribution can be substantial without becoming the headline. The headline is the engineering change you were responsible for making safe.

Verification is career evidence

The code is not verified because an agent says it is complete. Verification is the part that shows how you made the result trustworthy.

For a UI-library migration, preserve checks such as:

Inventory: search for imports and references to the old app-local components.
Contract review: compare exported names, props, variants, and composition patterns before and after the move.
Type and lint checks: record the exact command and result instead of writing “validated.”
Focused tests: run the tests that cover changed components and their most important consumers.
Repository check: confirm that the old shims are gone where they should be and that the new package is the source of truth.
Rendered review: inspect the affected screens when a shared component change could alter behavior or appearance.

Use the list to decide what to record; only an actual command and result prove that a check happened. If you did not run a check, leave it unknown. “I reviewed the diff and removed the shims” is more credible than “all tests passed” when you do not have the test result in your notes.

The same rule applies to agent output. Keep the generated patch, the review comments, and the final verification separate. A successful type check does not prove that the architecture is right. A clean visual review does not prove that every old import is gone.

The stronger version makes the verification engineer-owned. It also leaves room for an honest result when one of the checks finds something to fix.

Capture the review, not only the approval

A pull request approval is a useful artifact. It is rarely enough context for a future self-review.

Save the questions that changed the patch:

Did the agent preserve the public component contract?
Should this file be shared, or is it application-specific?
Is this cleanup part of the migration, or should it be a separate change?
Are the old shims still hiding an import path that needs to move?
What behavior would be expensive to discover after the package boundary changes?

Review comments show judgment when they explain what you checked and why you asked for a change. They also show that “the agent wrote it” did not mean “the agent decided it.”

Keep the review record safe to share. A private note can point to an internal pull request. A public career version can say “reviewed the package boundary and verified the affected consumers” without copying the URL, code, screenshots, or comments.

Describe the outcome without upgrading the claim

The architectural outcome of this migration is safe to state:

The shared UI primitives moved into the design-system package, and the application no longer needed the local UI shims for those components.

That is a real change. It is also narrower than a claim about productivity, quality, or adoption.

If you have evidence for a broader outcome, add it with its source and time period. For example, a measured reduction in duplicated components or a documented change in how another package consumes the primitives could support a stronger statement. Without that evidence, stop at the architectural outcome.

This is the same discipline I use when documenting engineering impact without perfect metrics. A migration can be valuable because it reduces ambiguity, removes an ownership boundary, or makes later work safer. You do not need to turn it into a productivity percentage.

Keep the evidence engineer-owned

An evidence record should be useful later without becoming a copy of the company repository.

Keep:

a general description of the problem;
the decision and the alternatives you rejected;
the categories of components or systems affected;
links to evidence you are allowed to retain, or a reminder of where the evidence lives;
the commands and checks you actually ran;
the final outcome at the level you can support;
a note about what can be shared publicly and what must stay internal.

Do not copy:

proprietary component code;
customer screenshots or data;
internal repository URLs if your policy does not allow them outside the company;
credentials, tokens, private configuration, or incident details;
exact metrics that are confidential or have no clear source.

You can preserve the engineering story without preserving the company’s implementation. A public version of this migration might say:

Migrated shared UI primitives from app-local implementations into a design-system package with assistance from a coding agent. Defined the package boundary, reviewed the generated changes, verified the affected consumers, and removed the local shims without expanding the work into a visual redesign.

That sentence is selectively shareable. It describes your contribution and the result while leaving out the repository, company, product, and internal links.

Use the record in a review later

When review season arrives, the raw migration note is still not the final self-review paragraph.

Use it to answer five questions:

What problem or constraint made the work necessary?
What decision did I make?
What did the agent contribute, and what did I personally review or change?
How did I verify the result?
What changed after the migration, and which part of that outcome can I support?

Then turn the answers into the smallest statement that remains defensible.

Context: Shared UI primitives lived in app-local implementations and shims.
Decision: Make the design-system package the shared home and move the work in stages.
Agent contribution: Helped with repetitive component and import changes.
My contribution: Defined the boundary, reviewed the patch, separated migration from redesign, and removed the local shims.
Verification: [record the checks you actually ran]
Outcome: Shared primitives now have a package-level home; [add a measured or observable follow-up only if sourced].
Share boundary: Public summary is safe; repository links and implementation details remain internal.

The software engineer self-review guide can help with the final presentation. This article’s job is earlier: preserve the source material before the polished sentence hides how the work happened.

The weekly career-capture habit is useful for the same reason. You do not need to write a finished career story after every agent session. You need to save enough context that future-you can reconstruct the judgment.

The code is only one part of the accomplishment

An AI agent may produce a large part of an implementation. That does not remove your responsibility for the engineering record.

Save the constraint. Save the decision. Save the rejected path. Save what the agent returned. Save what you changed. Save the checks. Save the trade-off. Save the outcome at the level the evidence supports.

That is what makes AI-assisted work legible as engineering work.

The result is a reviewable account of what you owned, what changed, and why another engineer should trust it.

Career Notes

Get better at proving your work.

A short newsletter for engineers who want clearer career stories, stronger self reviews, and better evidence before the next big conversation.