Claude Code for beginners

Translation of a guide from the project repository; the Czech original is authoritative. The project's documentation, task files, issues and commits are in Czech — Claude Code reads them for you, and you can ask it in English. Discord is Czech-speaking too, but English works as well.

A guide for someone who has never worked with Claude Code (or a similar tool). It assumes a finished development environment following local-dev.md or linux-install.md. How the project divides work between Claude in chat, Claude Code and a person is described in ai-workflow.md — this guide is about how to get started with Claude Code in practice.

Details about the tool itself are in the official documentation at code.claude.com/docs. Here are only the things you need for Shipard and the places where it's easy to make a mistake.

1. What Claude Code is

Claude Code is Claude running in the terminal, directly in the project directory. It reads files, runs commands, edits code and runs tests — on its own, step by step, according to what you write to it. You give it work in plain language and decide what happens with the result.

It differs from Claude in chat (claude.ai) in that it works directly in your checkout. In the project, chat is used mainly for design and verification; Claude Code for implementation. For everyday work Claude Code alone is enough (ai-workflow.md §1).

2. What you will need

• A development environment — Ubuntu in Multipass or in WSL following local-dev.md. Claude Code is installed inside Ubuntu, not on the Mac or in Windows.
• A paid Claude account — Pro, Max, Team or Enterprise (or an account in the Claude Console). The free plan doesn't include Claude Code.
• A GitHub account — once you want to send your work (chapter 8).

3. Installation and signing in

In the Ubuntu terminal (Mac: multipass shell shipard, Windows: the Ubuntu window):

curl -fsSL https://claude.ai/install.sh | bash

Then open a new terminal (or sign out and back in) and verify:

claude --version

If the claude command doesn't exist, the installer didn't add it to PATH — the solution is in the official documentation (Troubleshoot installation). Claude Code then updates itself.

Signing in: on the first run of claude, Claude Code asks you to sign in through a browser. There is no browser in the virtual machine — Claude Code prints a link; open it in a browser on your computer, sign in and paste any code the page shows back into the terminal.

4. First run

cd ~/sw/shpd
claude

• Claude Code asks whether you trust the files in the directory — confirm, it's your checkout.
• Don't run /init. The project already has CLAUDE.md — the file with the rules, which Claude Code loads itself at the start of every session.
• Type /context and check in the Memory files section that CLAUDE.md is loaded (and CLAUDE.local.md, if you created one — ai-workflow.md §7).

For a first try, ask about something that changes nothing, for example:

Explain to me how the economy module is organised in the project and where the tables are defined.

You will see Claude going through the files and putting the answer together. You end the session with /exit or Ctrl+D.

5. Permissions — what Claude may do without asking

Claude Code has permission modes. You switch them with the Shift+Tab key and the current mode is shown in the status line below the input field.

New versions of Claude Code start in auto mode. So at the beginning press Shift+Tab until you see manual mode on. Don't use the mode in which Claude skips all checks (bypassPermissions, --dangerously-skip-permissions) in the project.

When Claude asks for permission, read what it wants to run. Give the answer "yes and don't ask again" only to commands you understand (e.g. tests).

What the repo always guards. The shared settings .claude/settings.json in the repo apply in every mode, auto included:

• git push, gh pr create, gh pr merge — Claude always asks. It runs sending your work only on your explicit instruction, and you confirm it (chapter 8). If it asks about sending without you having asked for it, refuse.
• Reading the configuration and secrets of data sources (config/main.json, secrets/) is forbidden. The ban catches direct reading of the file; the application and its commands keep reading their configuration.

When Claude runs into a ban, it's not a bug — skip that step, or do it yourself.

6. How to assign work

A small thing (a typo, a minor fix, one function) — just write it, but specifically: what you want, where it is and how to tell it's done.

In the dev dashboard the "Upgrade All" button has an English label instead of a Czech one. Find where it's generated and propose a fix — don't change anything yet.

The sentence "don't change anything yet" is a useful habit: Claude first shows what it found, and you decide.

A bigger thing — in the project it is assigned with a task file in tasks/ (ai-workflow.md §2, format in tasks/README.md). Then it's enough to say:

implement tasks/task-name.md

Claude reads the task and the documents it refers to and proceeds according to it. The task is usually written by Claude in chat together with you, or you find one ready in tasks/ (state "naplánováno", planned).

Plan mode — for anything that touches more than one file, switch with Shift+Tab to plan. Claude explores the code and presents a plan; you approve it, adjust it or reject it.

One task = one session. Between unrelated tasks type /clear — Claude starts with a clear head and doesn't mix tasks up. When a session is long and Claude starts forgetting what was agreed, /compact helps (it summarises the conversation so far), but it's better to finish the task and start again.

7. How to check what Claude did

"Done" from Claude means that it thinks it's done. Verify it:

1. Read the changes. Ask Claude for a summary ("what exactly did you change and why?"), but go through the changes yourself too: git diff in the terminal, or the diff in your editor. Unexpected files among the changes are a reason to ask.
2. Look in the application. After a frontend change a build is needed (bash scripts/dev-update.sh) and a hard refresh in the browser (Cmd+Shift+R / Ctrl+Shift+R). After a change of tables or module configuration, shpd-server ds-upgrade-all.
3. Tests. Claude runs targeted tests itself; when you want to verify a specific thing, tell it to run the tests for that change. The whole suite takes long — leave it for the end.
4. When something doesn't fit, tell it as specifically as the assignment ("after saving the form, the new record doesn't appear in the list").

8. Repository, branches and sending your work

You don't have to know git and GitHub by heart — Claude knows them and uses the git and gh (GitHub in the terminal) commands itself. You only need to understand the terms and know which steps are yours.

Terms:

• commit — a saved and described set of changes;
• branch — your own line of commits in which you work without affecting the main branch stable;
• fork — your copy of the repository on GitHub; you can't write to the main repo shipard/shipard, you can to the fork;
• pull request (PR) — a request for the team to take your branch from the fork into stable. The team goes through it and merges it.

Once at the start — signing in to GitHub and the fork:

gh auth login

Then ask Claude:

Fork the shipard/shipard repository for me and set up the checkout so that origin is my fork and upstream the original repo.

With every piece of work:

1. Branch — "create a branch for fixing the label in the dashboard".
2. Work and checking — chapters 6 and 7.
3. Commit — "commit it". With a task, Claude commits according to its commit strategy. The commit is only on your machine for now, it hasn't gone anywhere.

4. Sending — only on your instruction. Ask Claude to prepare the PR description in a file ("write the PR description to /tmp/pr.md") and read it. Then:

   Push the branch to my fork and open a pull request to shipard/shipard with the description from /tmp/pr.md.

   Claude asks before the push and before opening the PR — read what it is sending and where, and confirm. It then prints the link to the PR. You can do the same step yourself in the terminal:

   gh pr create --repo shipard/shipard --body-file /tmp/pr.md

   gh asks where to push the branch (to your fork) and what the PR should be called.

5. Current state — before further work, "pull the changes from upstream into stable and create a new branch". After pulling, the dependencies and frontend update themselves (git hooks from the bootstrap).

Why you decide about sending: the repository is public. What leaves once, everyone sees — that's why Claude sends nothing on its own and you confirm every send. The repo enforces it technically too (chapter 5). Besides, only a few people may write directly to the main branch stable; everyone else sends pull requests.

9. Common pitfalls

• Public repo. Names of real companies, people or data sources don't belong in commits, PRs, issues or documentation — only the ID prefix (CLAUDE.md → Zdroje dat ve veřejných textech, data sources in public texts). The git hook checks typical cases on commit, but not all of them.
• The frontend "hasn't changed" — the build or a hard refresh is missing (chapter 7).
• A new table or field "doesn't exist" — shpd-server ds-upgrade-all is missing.
• A command hangs — it's waiting for a confirmation nobody gives in Claude Code (typically shpd-server fix-permissions without --dry-run; ai-workflow.md §4).
• Claude goes round in circles — stop it (Esc), describe what you see, and if need be start again with /clear and a more precise assignment.
• Claude "remembers" something that isn't true — Claude Code keeps its own notes (auto memory, /memory). They are only on your machine; what should apply to everyone belongs in a file (ai-workflow.md §5).

10. Where next

• ai-workflow.md — roles, process, rules, Claude in chat and remote-dev-bridge
• tasks/README.md — the format of tasks and their state; tasks in progress and planned ones are a good start
• README.md — the map of the documentation
• roadmap.md — where the project is heading
• Discord — when you don't know where to start, or get stuck