What a reviewer looks for when opening your GitHub
The reader is not always who you picture. A recruiter first checks whether the repositories are readable and recent. A hiring manager wants to know which kind of problem you are comfortable with. A technical lead opens one or two files and asks whether the decisions hold up. None of the three reads the whole codebase.
Three questions must be answered in under two minutes: which problem does this project solve, which decisions were made and why, and how do we know the result was acceptable. A repository that answers those three is worth more than a profile page covered in contributions.
The goal here is not to make you produce ten projects. It is to make what you already know how to do demonstrable.
Choosing which projects to show
Pin two or three repositories, no more. The selection criterion is not perceived technical difficulty but whether the project illustrates a skill you claim in your profile and applications.
- A project that overlaps the role you are targeting: one subject handled cleanly beats a spectacular but off-target one.
- A project you can talk about for twenty minutes in an interview without rereading the code.
- A project where a real constraint forced a trade-off: volume, cost, data quality, deadline.
- Possibly a shorter but very well documented project, used as a demonstration of method.
The remaining repositories do not need deleting. They simply should not be featured, and none of them should contradict what you claim to know.
Tutorial project versus a project that proves a skill
A repository built from a course or a tutorial is not disqualifying in itself. It becomes so when nothing shows what you brought to it. A technical reader recognises a tutorial layout instantly: same files, same dataset, same conclusion.
Weak presentation
"RAG chatbot over PDF documents. Stack: Python, LangChain, vector database, Streamlit. Run `app.py` to start."
Credible presentation
"Search assistant over 400 meeting notes, built because keyword search failed on internal vocabulary. Section-level chunking instead of fixed size, after seeing answers cut decisions in half. Hybrid search chosen over vector-only: project references are codes that vector search retrieved poorly. Evaluated on 40 questions written from real requests; the weak point is still questions spanning several meetings."
The second version does not describe a more complex project. It describes a project whose decisions are visible.
The README is the main deliverable
On an AI profile the README does the work the code cannot do in two minutes. It reads top down, from context to detail, not the other way round. A structure that works on any subject:
- Problem and context: what was not working before, and for whom.
- What the project does, in one sentence, plus a screenshot or an input/output example.
- Architecture: the components and, above all, the reason for each.
- Decisions and rejected alternatives: two or three are enough, if they are justified.
- Data: origin, volume, licence, known biases or limits.
- Evaluation: method, test set, results, including what fails.
- Limits and possible next steps.
- Running it: dependencies, environment variables, start command.
A concrete usage example — one query and its real answer, a screenshot of the interface, a short log excerpt — replaces paragraphs of description. It also spares the reader from installing anything to form an opinion.
Repository quality and reproducibility
Reproducibility does not have to be industrial. It has to be honest: either the project runs, or the README says plainly what is missing and why, for instance a dataset that cannot be redistributed.
- Pinned dependencies and install instructions tested on a clean machine.
- Configuration through environment variables, with an example file containing no secret.
- A sample dataset, reduced or synthetic, when the real data cannot be published.
- A few tests on the deterministic parts: parsing, transformations, output formats.
- A readable commit history, with no large files or sensitive data committed.
A repository that does not run and does not say so achieves the opposite of its purpose: the reader assumes it never worked.
Say what you actually did
On a team, academic or company project, your individual contribution must be explicit. One sentence is enough: which part you designed, which part you took over, what existed before you. That precision never weakens an application; its absence turns against the candidate as soon as the technical interview digs into a detail.
The same rule applies to assisted code. Using generation tools is ordinary today; presenting as your own design something you cannot defend line by line is not.
GenAI, RAG and agents, or more classical ML
The two families are demonstrated differently, and confusing them is expensive in interviews.
- GenAI, RAG, agents: the visible part is easy to produce; what stands out is document processing, retrieval strategy, the evaluation protocol, handling answers with no source, and behaviour on failure.
- More classical ML: value shows in dataset construction, validation suited to the problem, leakage handling, comparison against a simple baseline, and stability over time.
- In both cases: a metric chosen for the right reason and compared to a baseline beats an isolated score.
A live demo helps when it is stable and costs you nothing. A short video or two screenshots are enough when permanent hosting is not reasonable.
What is better left unpublished
A portfolio is also a judgement test. Publishing what should have stayed private disqualifies faster than an empty repository.
- Customer data, production extracts, internal documents, even hand-anonymised.
- API keys and credentials, including inside the commit history of a repository later made public.
- An employer's or client's code without written permission, even "cleaned up".
- Personal data, or datasets whose licence forbids redistribution.
- Projects abandoned at the first commit and featured as if they were finished.
When your most significant work is under a confidentiality clause, the answer is not to publish part of it: describe it in your profile and in interviews, through the problem, the constraints and the decisions, without exposing code or data.
Common mistakes
- Pinning ten repositories, seven of them without a README.
- Describing the stack and never the problem.
- Claiming a performance figure without saying on which set or against what.
- Leaving a single 900-line notebook as the only trace of the project.
- Making a company take-home exercise public.
- Featuring a project you can no longer explain six months later.
A credible portfolio is not an accumulation: it is a small set, consistent with what you say you can do, and defensible. Its natural continuation is the interview, where the same project has to be told as a chain of decisions rather than a list of tools.
Before you share your GitHub
Seven checks. Each takes minutes on the repository you put forward.
- The README says in three sentences which problem is solved and for whom.
- At least one architecture decision is justified, with the option you rejected.
- The origin of the data and its limits are stated.
- An evaluation method is described, however modest, with honest results.
- An outside reader can run it, or at least understand how it runs, without emailing you.
- What you personally did is distinguished from what the team did.
- No confidential material, no keys, no real customer data anywhere in the history.
Key takeaways
- Reviewers look for evidence of reasoning, not a collection of repositories.
- The README is the main deliverable: it is read before the code, often instead of it.
- A tutorial project is not disqualifying, as long as you state what you added to it.
- Evaluation is the rarest and most effective signal of seriousness.
- On GenAI projects, the difficulty shows in retrieval, evaluation and failure handling.
- Two owned repositories and an honest profile beat ten empty shopfronts.
- AI Engineering
- Evaluation