Contributing Into the Codebase: An AI Guide for Non-Developers

The team is working on one shared codebase: the git/GitHub system exists so multiple people can change it at the same time without overwriting each other. Claude Code is the interface for doing that in plain English instead of typing commands.

Part 1: The Workflow Loop

Sequence: clone → issue → branch → work → commit → push → PR/review → address comments → merge.

Run locally isn't a step in that line; it happens alongside "work," any time you want to check what you're building. Treat it as something you reach for throughout the loop, not a box to check off at the end.

1. Clone the repo"get your own copy of the blueprints"

"Clone the repo at [github URL] into a new folder."

The repo (repository) is the master blueprint of the house: every wall, wire, and pipe, plus the full history of changes. Cloning gets you your own working copy on your laptop, separate from everyone else's.

You only do this once per project. After that, you're just updating your copy.

2. Create an issue"put a sticky note on the fridge"

On GitHub, an issue is a written to-do: the shared list everyone can see, so work doesn't just live in someone's head.

"Create a GitHub issue titled 'Login button spacing doesn't match Figma' describing that the padding should be 16px per the design file."

3. Create a branch"work on a copy of the room, not the original"

An isolated copy of the code to work in, separate from main.

Like roping off a room and putting down a tarp before you repaint: you work in an isolated space so you don't disturb the finished house (main) while you're mid-change.

"Create a new branch for this issue and switch to it."

4. Work on it"the contractor is in the room with you"

This is the actual back-and-forth. You can hand Claude Code the Figma file or link directly.

"Here's the Figma link for the updated login screen: update the button spacing and colors to match it exactly."

"This component's font doesn't match the design system: fix it to use our Heading/Large token."

"Add an empty state for the search results screen, matching the illustration and copy in Figma."

4.1 Enabling Figma MCP

MCP is what lets Claude Code read your Figma files directly, from specs, components, tokens, instead of manually re-typing values. To turn it on:

If it's not already connected, ask Claude directly:

"Help me set up the Figma MCP connection."

Claude Code will walk through the actual steps for your setup, since this can vary slightly by environment. Once connected, you can just paste a Figma link into a prompt and reference it directly; no separate setup needed per task.

If something's off (wrong file, stale token, connection error), just describe what you're seeing and ask Claude to help troubleshoot; no need to know the mechanics of MCP itself.

5. Commit locally"photograph your progress and label it"

A commit is a saved checkpoint with a note describing what changed. It exists only on your machine at this point: like a labeled photo in your camera roll, not yet shared with anyone.

"Commit this change with a clear message describing what was fixed."

6. Push"upload your photos to the shared album"

Send your commits from your laptop up to GitHub so the team can actually see them. Before this, your work is invisible to everyone else.

"Push my commits to the remote repo."

7. Open a Pull Request & ask for review"call the site manager to inspect your room before it joins the main house"

A Pull Request (PR) is a formal request to merge your branch into main, with a diff (exact lines changed) for someone to check.

"Open a pull request for this branch, summarize what changed, and tag [reviewer] for review."

8. Address review comments"fix what the inspector flagged"

Expect this step to loop. Totally normal, not a failure; new commits get pushed to the same PR each round.

"The reviewer said the padding should be 16px not 12px on that button. Fix it, commit, and push the update."

"Take a look at [link] PR reviews and address those."

9. Merge"remove the tarp, the room is now part of the house"

Fold the branch into main. This step is usually the reviewer/developer's call. Flag it for review rather than merging yourself unless your team has said otherwise.

"This PR was approved. Merge it into main/master/dev/[main branch name]."

Run the dev stack locally"walk through the house yourself before it opens to the public"

Start the app on your own desktop so you can actually click around and see it as a real, working app, not just code. It's listed here for reference, but you'll typically do this early and often, most of all during step 4, not only once at the end.

"Start the app locally so I can preview it."

Getting the app running on your machine for the first time is usually the part non-engineers dread most: missing tools, unclear steps, config nobody wrote down. You don't have to fight through that by hand.

1. Give Claude Code as much context as you have, and ask the team before you assume there's nothing: is there a start guide, onboarding doc, wiki page, or architecture diagram?

   "Is there a README, onboarding doc, or architecture diagram for this repo? Read it and set things up accordingly."

2. Ask a developer for the environment variables and config the app needs; those are usually secrets and setup choices nobody can guess for you.

   "I need the .env values / config for local development, who can I get those from?"

3. Don't install, search for, or update libraries by hand. Let Claude Code handle package managers, versions, and dependency errors; that's exactly the kind of mechanical work it's good at.

   "This needs [library] installed, but I don't know the right version or command. Can you handle it?"

4. When something errors, don't panic and don't try to decode it yourself. Paste the error back to Claude Code and ask it to work through it with you.

   "I got this error when I ran it: [paste the error]. What's going wrong, and how do we fix it?"

Troubleshooting

• "There's a merge conflict": two branches changed the same lines differently. Flag this to a developer; it usually needs a human decision on which version is correct.
• "The dev server won't start": ask Claude Code directly: "The dev server isn't starting, can you check what's wrong?" It can usually diagnose missing setup steps.
• "I pushed but don't see my branch on GitHub": confirm the push actually succeeded: "Did that push work? Show me the output."
• "Claude Code says permission denied": usually a repo access issue, not something to fix locally. Check with whoever manages repo access.

Part 2: Fundamental Web App Knowledge

The big picture: how a click becomes a screen update

1. You click a button (frontend)
2. The frontend sends a request over the network
3. A server running the backend receives it, figures out what to do, maybe checks the database
4. It sends an API response back over the network
5. The frontend updates what you see

This loop happens constantly, but it's always this same five-step relay, whether it's loading a profile picture or submitting a form.

Frontend"the dining room and furniture the guests see"

Everything visual and interactive: layout, buttons, animations, scroll and click behavior.

• Component: a reusable piece of UI, like a button or a card; build it once, use it everywhere. This maps almost exactly to a Figma component.
• Responsive: the layout adapting to different screen sizes (phone vs. desktop).
• State: what the app currently "remembers": is the modal open? is the form filled in? Change the state, the screen re-renders to match it.

Backend"the kitchen and utility room nobody sees"

The logic behind the scenes: checking a password, calculating a price, deciding what content a specific user is allowed to see. Guests never enter the kitchen, but everything they're served comes from there.

Server"the building itself, always staffed"

A computer, usually far away in a data center, that's always on and waiting to respond; like a restaurant that's staffed and ready even when you're not there. When you run the dev server locally, your own machine is temporarily acting as that server with the same role, just reachable only by you instead of the public internet.

A few related terms you'll hear that describe how servers are set up, not different things from a server:

• VM (virtual machine): a computer simulated inside another computer, so one physical machine can run several isolated "servers" at once.
• Container / Docker: a lighter-weight version of the same idea: packages an app with everything it needs to run, so it behaves the same on any machine (a developer's laptop, a teammate's laptop, or the real production server). Solves "it works on my machine but not yours."
• Kubernetes (k8s): a system for managing many containers running across many machines at once; starting them, restarting them if they crash, distributing traffic between them. Relevant mainly at the scale of "many servers," not a single dev environment.

Network / API"the waiter carrying orders between dining room and kitchen"

The API (Application Programming Interface) is the fixed menu of things the frontend is allowed to ask the backend for: e.g. "get this user's profile," "save this comment."

The network is the trip the waiter makes to carry that request and bring back the answer. This round trip is why apps sometimes show a loading spinner; the waiter is walking to the kitchen and back.

Database"the pantry and filing cabinet"

Where information is stored long-term: accounts, messages, saved settings, orders. Only the backend goes into the pantry directly; the frontend just asks the waiter to fetch things from it.

Authentication vs. Authorization"checking ID at the door, then checking the guest list for which rooms you can enter"

• Authentication: proving you are who you say you are (logging in).
• Authorization: once you're recognized, deciding what you're allowed to see or do (admin vs. regular user).

Environments: local / staging (dev) / production"private walkthrough / dress rehearsal / opening night"

• Local: only on your laptop, only you can see it.
• Staging: a shared preview version the team can test before it's public.
• Production: the real, live app that real users see.

Real-world example

You post something on social media, close the app, open it the next day. The post is still there. You log in on a different phone, it's still there too. That single experience contains almost every core concept in web development. Breaking it apart:

• What you typed and tapped, on screen: the frontend. The visual, interactive part.
• Something checked you were logged in as you: authentication.
• Proving identity, separate from what you're allowed to do once identified (authorization, e.g. admin vs. regular user).
• Something remembered your post permanently, not just for that one session: the database. Long-term storage includes accounts, posts, settings. Nothing in the frontend itself is permanent; it only shows what it's told.
• Getting from "I tapped post" to "it's saved somewhere else, and shows up on a different phone": the network carries the request, the API is the fixed set of things the frontend is allowed to ask for, and the backend is the logic deciding what to do with that request: check the password, save the post, decide what content this user can see.

Put together, those pieces form the request/response loop that runs on every interaction, not just posting.

On top of that, this loop has to run somewhere: a server, possibly inside a VM or container, sometimes managed at scale by something like Kubernetes, and it runs in one of several environments on its way to being something real users can see: local, staging, then production.

Everything in the table below is vocabulary for parts of that same picture.

Terminology