A portfolio README does not need to tell the entire story of a project. It needs to let another person understand the problem, find an engineering decision, and see how to check the main claim. A gallery of screens may attract attention, but it does not explain what you chose, what you tested, or what you still do not know.

To write that README, organize the reading into five passes: problem, contribution, decisions, verification, and limits. The guide to what an AI software engineer portfolio should prove covers the collection of projects. This page focuses on the practical artifact: how to turn one repository into something that can support a technical conversation.

Diagram showing a portfolio README connecting a problem, decisions, verification, and limits.

Short answer

  • Explain what problem the project solves and for whom before listing the stack.
  • Show a decision that could have gone another way and the trade-off you accepted.
  • Give the reader a short path to install, run, and verify the main behavior.
  • Separate what you built, adapted, delegated, and reused.
  • State the limits, untested cases, and what you would change next.

What does a portfolio README need to prove?

A repository README has a broader job than personal branding. GitHub's documentation on README files describes the file as a place to explain why a project is useful, what it does, and how to get started. It also recommends telling readers where to get help and who maintains the project.

For a portfolio, add the question a reviewer is likely to ask: what kind of engineering can this project reveal? The answer does not need to promise seniority. It can point to one clear boundary, such as authentication, asynchronous processing, input validation, failure recovery, or evaluating a model output.

A useful opening answers four questions without making the reader open the code:

Question What the README should show
What is it? one sentence about the main behavior
Why does it exist? the problem, user or operator, and the scope limit
What did you do? your contribution and the parts you adapted or reused
How can someone check it? a command, input, expected output, or reproducible demo

The study Categorizing the Content of GitHub README Files analyzed 4,226 sections from 393 repositories. It found information about what a project does and how to use it frequently, while purpose and status appeared less often. The sample is from 2018 and does not measure hiring. It still suggests a useful portfolio question: does your README explain only how the project works, or also why it exists and what state it is in?

Start with the problem, not the technology

Open with two or three sentences that define the boundary. "Node.js API with PostgreSQL" names tools, but it gives a reviewer no decision to examine. "An API that records orders and rejects an update when the resource version has changed" names behavior and a risk that someone can discuss.

A personal project does not need real users or commercial production traffic. The README should say whether the project is meant to study a technique, demonstrate a contract, or explore a hypothesis. That keeps a reader from assigning the project a promise you never made.

Use a simple top section:

# Project name

One sentence about what the system does and who it is for.

This project explores [problem or technique]. It covers [scope]
and does not attempt to solve [out of scope].

## Quick demo

Command or link that shows the main path.

The GitHub guide to making a repository collaboration-ready also puts the project's purpose, usage, and maintenance in the README. For a portfolio, maintenance includes saying whether the repository is active, frozen, experimental, or limited to a demonstration.

Record decisions that the code cannot explain

A dependency list does not show judgment. For each chosen decision, record the risk it addresses, the alternative you considered, and the cost you accepted. You do not need to document every syntax choice. Pick one or two decisions that change behavior, operation, or the ability to verify the project.

Decision Question the README answers Useful evidence
Storage Why does this database or file fit the scope? query, data model, or stated limit
Concurrency What happens when two actions arrive together? test, conflict rule, or uncovered scenario
Failure How does the system react to a timeout or invalid input? fixture, error state, or redacted log
AI dependency What was delegated and how was the output checked? diff, test, criterion, or rejected decision

A short record works best when it connects cause and consequence:

## Decision: reject an update with an old version

I compare `version` before writing because two requests may edit the same
resource. The alternative was last-write-wins, but that would hide a
concurrent change. `npm test -- conflict` shows the accepted and rejected cases.

The example is illustrative. Replace the command, risk, and decision with things that exist in your project. A README that describes an architecture the code does not have creates weaker evidence than a short, honest README.

Show a verification path

A demo helps, but a demo by itself does not explain how the result was produced. Write the shortest path another person can repeat:

  1. which versions, prerequisites, or variables are required;
  2. which command installs and which command starts the project;
  3. which input represents the main case;
  4. which output or effect someone should observe;
  5. which failure case shows the implementation's limit.

If setup requires a secret, paid service, or private account, say so. Include a safe example, a local mode, or a description of what cannot be reproduced. GitHub's documentation expects a README to help people get started, but that does not mean promising a zero-configuration run when the project cannot provide one.

The test does not have to be large. npm test, a small fixture, or an input/output example may be enough for the chosen question. For a project that uses a model, record the evaluation criterion and one input that should be rejected. A fluent answer does not prove consistent behavior.

Do not put a result in the README that you did not run. If a command is only an example, label it "illustrative." If you checked a local fixture, state the environment and what it does not cover. That distinction is part of the evidence.

Explain authorship without turning the README into a defense

A reviewer needs to know which parts can be attributed to you. That matters for a group project, fork, tutorial base, or project assisted by AI.

Use a short section:

## Authorship and contribution limits

I implemented the API contract, validation, and conflict tests.
I adapted the initial configuration from [source]. I did not measure
production load, and I do not claim that the project covers database recovery.

You do not need to publish an entire conversation with an agent. If you used Codex, Claude Code, or another tool, explain what you delegated, what you reviewed, and what proof you ran afterward. For long sessions, the author uses RemoteCode to keep context between sessions. That describes the work method; it is not evidence that the project is high quality.

The checklist for evaluating a software engineer portfolio reads from the other side. It asks whether contribution, decisions, verification, and limits are visible. Use those questions to review your own README before asking someone else to assess it.

State what has not been proven

A portfolio project becomes easier to trust when it separates three states:

  • Not implemented: the function does not exist.
  • Not verified: the function exists, but the available proof does not cover the case.
  • Out of scope: the project does not attempt to solve that situation.

This distinction avoids two kinds of exaggeration. The first is calling a demo production-ready. The second is hiding a useful project because it does not have the scale of a commercial service.

Tie the limits to the decisions you showed. If you chose SQLite to keep setup simple, say that the choice does not prove behavior under distributed load. If you use an external API, say that the fixture does not verify provider availability. If an agent generated part of the code, say which review and tests remain your responsibility.

Also state the repository status: active, frozen, experimental, or archived. A reader needs to know whether an open issue represents work in progress or an abandoned decision.

Keep the README separate from long documentation

The README should get a reader to first use and the main proof. It does not need the full API reference, every commit's history, or a complete operations manual. GitHub's documentation on wikis distinguishes a README, which quickly explains what a project can do, from longer documentation.

Move lengthy details into docs/ when that makes the README easier to read, but make the path explicit:

README.md                 problem, main decision, and quickstart
docs/architecture.md      design and discarded alternatives
docs/testing.md           fixtures, commands, and proof gaps
docs/operations.md        configuration, recovery, and maintenance

Do not use the split to hide the important information. The README still needs the problem, the first path, the decision you want to discuss, and a direct link to supporting evidence.

Checklist before publishing

Read the README as someone who does not know the project. Can you answer these questions without opening five files?

  • Does the project explain the problem and what is out of scope?
  • Does the first block say what to do and what to observe?
  • Is there an engineering decision tied to a risk or requirement?
  • Does it name the rejected alternative and accepted trade-off?
  • Was the install command checked in a clean environment, or is it marked illustrative?
  • Does a test, fixture, or example show the main behavior?
  • Is there a failure case, limitation, or verification gap?
  • Does authorship separate what was built, adapted, delegated, and reused?
  • Is the repository status clear?
  • Do the links to longer documentation work?

If one answer is "no," that does not mean the project needs to grow. It means the README does not yet prove that claim. Fix the documentation, reduce the promise, or remove the claim.

Conclusion

A portfolio README is a review path. It starts with the problem, shows a decision with a consequence, points to a way to verify the behavior, and ends with the limits that remain open. The technology matters, but it does not carry the proof by itself.

Write for the conversation the project can support. If you cannot explain why a choice exists or which test could contradict it, the README should not manufacture confidence. Short, reproducible, honest documentation prepares a better technical discussion than a page full of badges and adjectives.

How this article was produced

Samuel Fajreldines is the accountable author for this article. The research compared current GitHub documentation, an academic study of README content, and recent public discussions among Brazilian developers. The checklist is an editorial synthesis. It is not the result of a real interview, a measured hiring process, or a portfolio benchmark.

AI assistance supported source discovery, organization, first drafting, localization, SVG illustration, and consistency review. It did not evaluate candidates, run another person's portfolio project, or supply professional experience the author has not demonstrated.

Sources consulted