Don't Let the First PR Die in the README: Onboarding Contributors to an AI-Built Repo

The thing an AI-generated repository fears most is not a lack of stars. It is the would-be contributor who opens the repo, stares at it for half an hour, and quietly closes the tab. The code is all there, the docs look polished, yet the newcomer has no idea where to start: which line can be changed without breaking something else? Which secrets does it need to run? What does that agent rules file actually govern? And if they open a pull request, will it be bounced with a vague "doesn't fit the architecture"?

This guide is not about user onboarding — that is for people who use the product, and the site already covers it. Nor is it about open-source release, which is the act of pushing a repo out into the world. It answers one narrower question: when an outsider wants to contribute code to your AI-built repository, how do you get them to a first merged pull request within seven days, and make them want to open a second one? It is written for solo developers and small teams whose repos share a specific trait: most of the code was generated by AI, the original author's memory is not in the code, and agent rules and prompt history are scattered around.

First, the boundary: newcomers get stuck somewhere you don't expect

The classic newcomer problem in open source is "too much code to understand." The AI-generated repo has the opposite problem: every line looks understandable, the comments are all tidy, and the newcomer still does not dare touch anything. Four reasons, all directly tied to AI generation.

First, missing author memory. In a hand-written project, the author carries context like "this awkward code is a deliberate compromise." In an AI-generated project, that context lived in a chat session that is now closed, and it is nowhere in the repo. A newcomer looking at an awkward piece of code cannot tell whether it is a considered trade-off or something the model just made up.

Second, rules in several places at once. How the agent works might be documented in AGENTS.md, in editor rules, in one section of the README, and in CI configuration — and the newcomer does not know which one wins. Worse, some of them may be stale: the rules say "use Prisma" while half the code still runs hand-written SQL.

Third, an underestimated setup cost. An AI-written README often says "just run npm install," without mentioning three third-party keys, a local database, and a specific Node version. The newcomer stalls at step one and feels too embarrassed to ask — because the docs said it was easy.

Fourth, an invisible review bar. The newcomer does not know what a PR in this repo is actually judged on: correctness? Style consistency? Or "don't touch the agent-generated parts"? When the bar is unwritten, newcomers can only guess, and one wrong guess can be the last one.

So the goal of a contributor onboarding guide is not "thicker docs." It is to eliminate those four problems one by one: write the memory into the repo, converge the rules into one place, turn setup into copy-pasteable commands, and turn the review bar into a checklist.

Four maps: what a newcomer should read first

Do not let newcomers wander from the root file listing. Give them four maps, each explainable on one page, placed where they cannot miss them, and linked to each other.

The first is the product map: who the product is for, what problem it solves, which three features are core, and which pages form the main flow. State the positioning in one sentence, then link to the entry files of the main flow. No vision slogans — write "the user opens the homepage, clicks this button, and this happens."

The second is the code map: what each directory does, where data flows, which modules matter most, and which directories are generated and should not be hand-edited. Mark the "no-go zones" explicitly: the migrations directory, generated API clients, wrapper layers around third-party SDKs. A no-go zone does not mean "don't look" — it means "don't change this on your first visit."

The third is the agent map: which agent workflow the repo uses, which file holds the rules, where prompt templates live, and how AI-generated code is marked. State three things plainly: what a newcomer must follow when using AI assistance themselves; which manual checks AI-generated code must pass before submission; and which decisions must be made by a human, never delegated to a model.

The fourth is the decision map: which key decisions were made, why, and which alternatives were rejected. Keep it lightweight: one small file per decision under docs/decisions, covering background, options, decision, and consequences. Without a decision record, every change a newcomer makes is an argument with an invisible history.

The test for all four maps is simple: hand them plus the repo to someone who has never seen the project, and after 30 minutes ask: "If you had to fix a typo on the login page, which file would you change, how would you verify it, and what would you write in the PR?" If they can answer, the maps pass. If not, whichever map failed to answer is the one you need to write.

A seven-day plan: turning "contributions welcome" into a schedule

"All contributions welcome" is the least effective welcome there is. Newcomers need a road with a destination. Here is a seven-day plan for a part-time contributor, ready to copy into CONTRIBUTING.md. It assumes about an hour a day; in a hurry it compresses into a single weekend.

Day zero: get it running. The only goal is to run the project locally and see the main flow. When any step disagrees with the docs, the newcomer writes it down immediately — that is already their first valuable feedback. The maintainer's job: provide a .env.example where every variable says where to get it and whether it is required; make the database initializable with one command; make seed data generatable with one command.

Day one: read the maps. Go through the four maps in order, then leave one sentence in an issue: which map was least clear. That sentence is itself a contribution and needs no code. The maintainer must reply fast — within 24 hours, even if the reply is only "noted, I'll fix that map this weekend." What newcomers fear most is not a hard task but silence.

Days two to three: do one small thing that needs no global understanding. Pick a level-one task from the ladder below — fix a typo, add an empty-state line, extract a hardcoded string into a constant, add a unit test for an existing function. The rule: the change touches at most three files, and the acceptance criteria are written into the task.

Day four: open the first PR. Fill in the PR template (below), get CI green, attach a screenshot or recording. This PR does not need to be big; it needs to be complete: description, change, verification, and risk, all four present. When reviewing, the maintainer should first acknowledge "you got the whole flow working" before discussing code details.

Days five to seven: retrospective and next task. Maintainer and newcomer review together: which step stalled longest, which doc misled. The conclusions go straight into the docs — the pitfalls one newcomer walked through become signposts for the next. Then pick a level-two task and settle into a normal contribution rhythm.

The most important line in the whole plan is this: treat reply speed as infrastructure. A newcomer whose issue sits unanswered for three days has just been told, in front of every onlooker, that "this repo does not welcome outsiders." If you are genuinely too busy, write the rhythm into CONTRIBUTING.md — "replies every Wednesday and Sunday" — rather than making newcomers guess.

The task ladder: how to write level-one, level-two, and level-three tasks

A good first issue is not "easy." It is "bounded." Keep a task pool in three levels so newcomers climb and maintainers control risk.

Level-one tasks change one place and affect one place. Examples: fix a typo, add a hint to an empty state, extract a hardcoded string into a constant, add a unit test for an existing function. Every level-one task must state: which file to change, what counts as done, and how to verify (a command or a screenshot). Never write "improve the homepage a bit" — a task with no definition of done is a rework waiting to happen.

Level-two tasks change one piece of logic with limited blast radius. Examples: add a sort option to a list, add a validation rule to a form, fix a minor bug with reproduction steps. Attach the reproduction steps, the relevant files, the expected behavior, and the neighboring modules to leave alone. Also state whether the approach needs discussion first — if it does, agree on the approach in the issue before anyone writes code, to avoid wasted work.

Level-three tasks span modules or touch architecture. Examples: change a caching strategy, refactor a module, integrate a new third-party service. Level-three tasks are not open for newcomers to claim, but they are open for "write the proposal first": the newcomer submits a design doc, the maintainer approves it, then implementation starts. That is how a level-three task becomes a level-two task — and how you test whether a newcomer understands the architecture.

The pool itself needs discipline: tag every task with its level; mark claimed tasks with the claimant and date, and auto-release anything untouched for over two weeks; archive finished level-one tasks instead of leaving them around to pad the list. A pool full of stale, unowned tasks discourages people more than having no pool at all.

PR template and review checklist: make the bar visible

The review comment newcomers fear most is "this doesn't feel right." Turn the bar into a template and a checklist, and feelings become fact-checking. Here is a PR template ready to save as .github/pull_request_template.md:

## What changed (one sentence)
## Why (linked issue number)
## How verified (commands / screenshots / recording)
## Blast radius (which modules changed, any no-go zones touched)
## AI assistance used? (which tool, which parts were manually checked)

The last item is not an interrogation. It is an honesty mechanism for an AI-generated repo: using AI is normal, and stating it tells the reviewer where to look hardest — for example, at edge cases the model refactored, or at a third-party API usage it wrote "confidently." The review checklist is for the maintainer, ticked item by item on every PR:

• Does the change do exactly one thing? Drive-by refactors spanning more than three files get sent back for splitting.
• Did it touch a no-go directory? If so, is there a stated reason?
• Do the tests cover edge cases for the new logic, not just the happy path?
• For AI-generated parts, were high-risk points manually checked — third-party APIs, permissions, money, time?
• Did docs change with the code? Code without docs means the next newcomer trips on the same stone.
• Do breaking changes come with migration notes? Database fields, API responses, environment variables — one line per changed item.

Tone matters too: start with "this PR solves X, thank you," then "I suggest changing this part, because…," and end with "once that's done I can merge." What a first-time contributor fears most is not knowing whether the next version will pass. Put the verdict at the end so they revise with certainty.

Three rules for AI-generated code

Contributors using AI to write code is not the problem. Having no rules is. Put these three rules in AGENTS.md or CONTRIBUTING.md — and apply them to the maintainer's own PRs too, because rules that bind only newcomers are rules nobody trusts.

Rule one: AI must not be the sole author. For any AI-generated change, the submitter must be able to explain three things: what the code does, what its edge cases are, and how a failure would be verified. If they cannot, shrink the change until they can. This blocks "pasted a huge model output" without blocking "used the model to move faster, but took responsibility."

Rule two: high-risk points get manual review. Keep a high-risk list in the repo: permission checks, payment amounts, password and secret handling, delete and bulk operations, third-party API parameters and return values, time and timezone math. Anything touching the list gets one extra sentence in the PR description: "I manually verified X, based on the official docs / test result." Reviewers seeing that sentence know exactly where to double-check.

Rule three: generated code leaves a trace. Ask PRs to state the degree of AI involvement: "model drafted, I rewrote the critical parts," "model only added tests," or "fully hand-written." This is not for judgment — it is for debugging later. When a piece of code breaks, the maintainer can tell whether it is leftover model hallucination or a human design mistake, and the two are fixed differently.

Beyond the three rules, state one red line up front: never paste secrets, real user data, or production database connection strings into any AI chat or issue. Newcomers to AI-generated repos often paste real configuration "so the model can reproduce the problem." One sentence on the CONTRIBUTING.md front page closes that hole.

A worked walkthrough: one fictional example, end to end

Imagine the repo is an AI-generated expense tracker: users log spending, a list rolls up by month, data lives in a local database. The task pool holds a level-one task: "The currency symbol on the settings page is hardcoded to RMB; make it follow the currency the user picked in settings." The task states the files (the settings component and the amount formatter), the definition of done (switching currency updates the list and detail pages), and verification (run the existing tests and post a before/after screenshot).

The newcomer follows the seven-day plan. On day zero, running the project reveals that the README omits the database init command; they note it and open a two-line docs PR — their first merged change. On day one, reading the maps, they notice the code map never says whether the amount formatter is a no-go zone; they ask in an issue, the maintainer replies the same day and adds the label. On days two to three they do the currency task: two files changed, one test added, all five PR template fields filled. Review raises one point: the formatter also needs a fallback when the currency symbol is missing. The second version merges the same day, and the maintainer adds their name to the contributor list.

The key detail: the newcomer's first PR was not the currency task, but the docs fix. That is what the ladder is for — first establish, with a two-hour job, the trust that "this repo takes me seriously," then take on work that needs business understanding. Hand a newcomer "refactor the amount module" on day one and even a capable one will stall on review anxiety. Get the order right and ability follows; get it wrong and no task pool can save you.

Anti-patterns: five ways to drive newcomers away

First, a README that says "easy" for a setup that takes half a day. Every step in the docs must have been executed literally by someone — ideally the previous newcomer. Docs are not written; they are walked into existence by newcomers tripping over them.

Second, issues titled "help wanted" or "improve this," with no reproduction steps and no definition of done. A newcomer claiming such a task is claiming a rework. Maintainers should rather post fewer tasks than post vague ones.

Third, reviews that say "no" without saying "how to get to yes." Every round of review feedback must carry an executable next step, or the newcomer guesses, guesses wrong, gets bounced again, and leaves after two rounds.

Fourth, a merge bar that moves with the maintainer's mood: merging an untested PR in a rush today, rejecting a tested one tomorrow. Newcomers will instantly learn "the rule here is who you know," and leave.

Fifth, treating newcomers as free labor: only dirty work, no background, no public thanks. What actually retains contributors is two things: being reviewed seriously, and being thanked publicly. Writing a name into the changelog or the README contributor list costs nothing and does the most.

Maintainer pre-flight checklist: before you announce "contributions welcome"

A final checklist for maintainers — tick every box before opening the door:

• All four maps exist, and each links to real files, not slogans.
• The local setup steps have been executed literally by someone who had never seen the repo.
• The task pool holds at least five level-one tasks, each with a definition of done and a verification method.
• The PR template is in the repo, and the review checklist has been used by the maintainer at least once.
• The three AI rules are in AGENTS.md, and the maintainer's own PRs follow them.
• The reply rhythm is written down: how many days for issues and PRs, even when busy.
• There is a place to write contributor names, ready to fill on the very first merged PR.

Once that is done, the repo is genuinely open. AI can generate ten thousand lines of code overnight, but it cannot generate a person willing to stay. People stay because of a map, a small task, and one review that took them seriously. Get those three ready, and the first PR will not die in the README.