Open your repository and look for the part another person can verify without speaking to you. If they find only a polished screen, a few prompts, and a deploy button, the project shows that you built a demo. It does not yet show that you can do software engineering with AI.

In 2025, 46% of developers said they distrust the accuracy of AI tools, while 33% said they trust it, according to Stack Overflow's 2025 Developer Survey: AI. A portfolio needs to answer that doubt with evidence, not with a list of models you used.

This checklist turns a project assisted by Claude Code, Codex, or another agent into a technical case that a reviewer can read, run, and question. You do not need to hide your use of AI. You need to show where the system, tests, and your judgment enter the process.

Quick decision

  • Choose a problem that reveals engineering decisions, not only a model call.
  • Show architecture, boundaries, tests, failures, and operations in the same repository.
  • Explain what was generated, what you reviewed, and what remains unproven.
  • Make it possible to form an opinion without opening your agent conversation history.

What does an AI software engineer portfolio need to prove?

An AI software engineer portfolio is a public set of projects that shows how you decide, build, and verify software with AI tools. A strong portfolio takes a change from a problem to a verifiable decision. The demo may use an agent, but quality appears in the contract, system boundaries, failure cases, and how you measure the result.

The project does not need to be large. It needs a question that cannot be answered by copying a tutorial. An agent that reads a codebase, calls tools, retrieves context, stores state, or opens a pull request reveals much more about your practice than a chat with no consequences.

For each project, write a proof sentence: "After reading this repository, a person should conclude that I can do X with Y and verify Z." If you cannot finish the sentence, the scope is still too broad.

The post about software engineering skills for coding agents explains the skills behind this proof. This article focuses on what to make visible so another person can evaluate them.

Citable summary: An AI software engineer portfolio must prove more than code generation. The project should make the problem, system design, automation limits, result verification, and known failures visible. The agent is part of the process, not the complete evidence.

Which problem belongs in the portfolio?

The best portfolio project has a technical tension that is easy to explain: incomplete context, state between steps, a permissioned tool, an output that needs evaluation, or a change that could break a product rule. That kind of problem lets you show choices and consequences.

An application that only sends a question to a model can be useful for learning. It is weak as professional evidence if it has no reason to exist beyond the generated answer. The question worth publishing is: what could go wrong, and how would the system know?

Choose a slice that fits the repository and can be demonstrated. A code review agent could receive a diff, consult project rules, flag risks, and produce a reviewable decision. A support agent could retrieve permitted data, record the source, and refuse an answer when it finds no evidence.

Do not turn the project into a collection of technologies. MCP, RAG, queues, and orchestration are means. The project should explain which boundary each one protects. When a tool is no longer necessary, record that decision too. Knowing what not to use is part of the work.

A useful signal: the README starts with the problem and the success criterion. The stack comes later. The reader understands what you decided before discovering which library you installed.

What evidence should appear in the repository?

An AI-assisted project becomes more convincing when the repository contains evidence of intent, construction, and verification. The reviewer does not have to trust your description. They can follow links, run a command, read a test, and find the risk you chose not to hide.

Diagram showing a README, architecture, test, and risk becoming an engineering review.

Use this matrix before publishing:

Evidence What it should answer What becomes visible
Problem Who needs this and what behavior should change? Issue or README with scope and out of scope
Architecture Where do state, model, tools, and permissions live? Short diagram and recorded decision
Implementation Which part is deterministic and which depends on the model? Code separated by clear boundaries
Verification How do you know the output is correct? Test, eval, fixture, or reproducible command
Operations What happens with timeouts, cost, errors, and sensitive data? Logs, limits, alert, or operations section
Limits What does the project still not guarantee? An honest residual-risk section

This set is more useful than a folder full of screenshots. The image helps people find the project. The README and artifacts help them form an opinion about it.

For coding agents, include the diff from a real task or a small sample showing how the agent received context. Do not publish secrets, personal data, or logs that reveal credentials. What matters is the work boundary and proof that you checked it.

Imagine an agent that reviews a pull request. The project is easier to evaluate when the flow is more than "the model commented on the diff" and becomes a record connecting input, rules, checks, and a decision:

{
  "input": "pull request diff",
  "checks": ["tests", "permissions", "business rule"],
  "decision": "needs-review",
  "evidence": ["sanitized log", "verification result"],
  "residualRisk": "not tested under real load"
}

An eval is a repeatable evaluation that compares an agent output with a criterion defined before execution. It can be small if the repository shows inputs, expectation, result, and limits. OpenAI's Evals design guide helps separate a manual demo from a check that can be run again.

The article about PR evals for coding agents in CI shows how to connect verification to an integration flow. You can adapt the idea for a personal project without building a complete platform.

How do you show that AI did not hide your reasoning?

Declare the agent's use as part of your method. Say which task it performed, which constraints it received, and which parts you reviewed manually. That is more honest and more useful than claiming the code was written "from scratch" when the repository shows an assisted workflow.

A short authorship section can use this structure:

## Agent use

- The agent investigated the codebase and suggested the initial plan.
- I defined the contract, reviewed the changes, and changed the scope.
- Tests and evals ran outside the agent conversation.
- I made the decisions about permissions, failures, and sensitive data.
- Still unproven: behavior under real load.

The value is not in labeling every line as human or model written. It is in separating suggestion, execution, and verification. A reviewer wants to know whether you understand what the system does and can find a plausible answer that is wrong.

In long Claude Code and Codex sessions, RemoteCode helps continue agentic flows with less repeated context. It is the author's own tool, mentioned here because the context budget is part of the method. It does not replace review, tests, or responsibility for the result.

When the agent opened a PR, preserve what matters for reading: the original request, accepted plan, final diff, executed verification, and risk decision. You do not need to publish a full transcript. A faithful summary is better than an impossible-to-review history.

Citable summary: Declaring AI use strengthens a portfolio when the project separates suggestion, execution, and verification. The candidate shows what the agent did, what they decided, which tests they ran, and which limits remain. Transparency turns shared authorship into reviewable evidence.

What should a README contain to survive a first read?

A good README reduces the reviewer's work. It starts with the problem, shows the architecture in a simple image or diagram, offers a way to run the project, and points to the most important proof. It should not make the reader guess which part of the repository deserves attention.

A short structure is often enough:

# Project name

## Problem
What happens today and which behavior this project changes.

## Decision
Which boundaries shaped the architecture and what stayed out.

## Flow
How input, agent, tools, state, and verification connect.

## Run it
Prerequisites, non-secret variables, and reproducible commands.

## Proof
Tests, evals, fixtures, failure examples, and observed result.

## Operations
Timeouts, retries, permissions, costs, and observability.

## Limits
What still depends on review or data not included in the repository.

Do not use a results section to imply precision you did not measure. If there is no evaluation set, say that you have targeted tests. If the deploy is local only, write that. A clear limitation increases confidence in the part you did demonstrate.

Your GitHub profile README can present your professional direction, but it does not replace the README for each project. GitHub also lets you pin items to your profile. Use the profile to point the way and the repository to show the proof.

Which signals weaken an AI portfolio?

The first weak signal is a demo gallery with no contract. The reader sees that something answered, but cannot discover which input was valid, which output was expected, or how you would detect a regression.

The second is a list of tools that takes more space than the decisions. Naming models, libraries, and providers does not show that you know how to choose between them. Explain a concrete trade-off: larger context or on-demand retrieval, retry or human intervention, autonomy or narrow permission.

The third is hiding operations. An agent that looks correct in a recording can fail when a token expires, a tool is slow, the response is empty, or a worker restarts. The post about coding agent observability in CI shows which signals make this type of failure investigable.

The fourth is publishing generated code without reviewing the boundaries. A large repository is not automatically a strong repository. Remove abstractions without a reason, keep the flow readable, and show the test that would disprove the main hypothesis.

If you use an agent to generate the portfolio, apply the same standard to the site itself. Generic copy, unsourced numbers, and vague promises are editorial engineering failures too.

How should you review the project before presenting it?

Run a review that simulates the evaluator. Start in a clean window, without the memory of building the project. Open the README, follow the run path, and try to answer which problem was solved before looking at the implementation.

Then walk through these questions:

  • Does the project have a user, an input, and a result that can be described without jargon?
  • Does the diagram show who controls state, permission, and external effects?
  • Is there a proof that could fail, and does it actually fail when you break the rule?
  • Does the code distinguish model errors, tool errors, and product errors?
  • Can the run be repeated without duplicating an effect or losing context?
  • Does the README say what was not measured, deployed, or verified?
  • Can another person run the example without secret credentials?

If an answer depends on "trust me", turn it into an artifact. It could be a test, sanitized log, diagram, closed issue, or architecture decision. The goal is not documentation for its own sake. It is to remove doubts that would make a fair evaluation impossible.

Use context engineering for coding agents without waste as a reference for organizing larger problems. A small, well-chosen context also makes your explanation easier to read.

Final checklist: scoped problem, readable architecture, runnable code, a test that can fail, operations described, AI use declared, and residual risk visible.

Frequently asked questions about AI software engineer portfolios

Can a project that is too simple still belong in a portfolio?

Yes, if it reveals a decision you can explain and verify. A small project with a validated tool, limited permission, a failure test, and a clear README can prove more than a large system with no success criterion. Size matters less than evidence quality and honesty about what is still missing.

Do I need to publish all code generated by the agent?

No. Publish the code needed to run and review the idea, remove secrets, and explain what you omitted. The point is to show an implementation you understand and can support. A complete conversation transcript rarely helps; the contract, diff, tests, and decisions are more useful artifacts.

How can I show Claude Code or Codex experience without turning the article into advertising?

Describe the agent as part of the workflow, not as the outcome. Explain where it investigated, proposed, or executed a task, and show which checks happened outside it. The proof comes from the repository, tests, and decisions. The tool name is context, not enough of an argument.

Should I put metrics in the README?

Yes, when you measured the metric with a method another person can understand. Report the test set, period, environment, and comparison limit. If you did not measure it, write a qualitative note. A number without a method can look precise and weaken the rest of the project.

Does a portfolio need to show real production?

Not necessarily. A local deploy or demonstration environment can be enough when the project explains the run path and limits. Real production helps show operations, but it should not be invented. You can demonstrate operational readiness with simulated failures, sanitized logs, limits, and an observability plan.

Sources consulted