Lab 2.2: Run `/init` and Explain `AGENTS.md`¶

Goal¶

By the end of this lab, you will: 1. Run OpenCode in a real project directory. 2. Use /init to generate an AGENTS.md file. 3. Read AGENTS.md like a project instruction manual. 4. Explain the project's conventions in your own words. 5. Notice where the agent guessed correctly, guessed vaguely, or got something wrong.

Estimated time: 35-45 minutes.

Why This Lab Matters¶

In Lab 2.1, you asked OpenCode to fix a tiny typo. That was useful, but the project was simple.

Real projects are different. They have folders, tests, build commands, naming patterns, formatting rules, and team habits. Before an agent edits a real project, it needs context.

That is what /init is for.

/init asks OpenCode to inspect the current project and create an AGENTS.md file. That file tells future agents: - What kind of project this is. - Which files and folders matter. - Which commands are useful. - Which conventions the agent should follow. - Which actions are out of bounds unless the human explicitly asks.

Think of AGENTS.md as a short onboarding note for any AI agent that works in the repo.

Before You Start¶

You need: 1. OpenCode installed from Lab 2.1. 2. A working model provider, such as Anthropic, OpenAI, or Ollama. 3. Basic terminal comfort with cd, ls, and git clone. 4. A project folder you are allowed to inspect.

You do not need to understand the whole codebase. Your job is to practice reading the agent's project map.

Project Choice¶

For this lab, use one of these options.

Option A: Provided Course Project¶

If your instructor has provided a Week 2 sample repo, use that. It may be named something like:

week-02-init-sample

Open a terminal and move into that project:

cd path/to/week-02-init-sample

Option B: Small Open-Source Project¶

If you do not have a provided repo, choose a small open-source project. Good beginner choices are: - A small JavaScript package. - A small Python utility. - A documentation site. - A repo with fewer than 100 files.

Avoid very large projects for now. Do not use Linux, React, Next.js, Django, Kubernetes, or any large framework repo for this lab. The goal is to understand the output, not drown in files.

Clone your chosen repo:

git clone https://github.com/some-owner/some-small-project.git ~/opencode-init-lab
cd ~/opencode-init-lab

If you are unsure what to use, ask your instructor for the recommended Week 2 repo.

Safety Rules¶

For this lab: 1. Stay in plan mode unless the lab explicitly tells you to switch. 2. Do not ask the agent to change code. 3. Do not run install commands like npm install, pip install, or cargo build unless your instructor says to. 4. Do not paste API keys, passwords, or private tokens into OpenCode. 5. If OpenCode asks for permission to do something you do not understand, stop and ask for help.

/init may create or update AGENTS.md. That is the only project change expected in this lab.

Part A: Inspect the Project Yourself First¶

Before you ask the agent to inspect the repo, take two minutes to look around yourself.

Run:

ls

Look for files such as: - README.md - package.json - pyproject.toml - requirements.txt - Cargo.toml - src/ - tests/ - docs/

Write quick answers:

What do you think this project does?
What language or framework do you think it uses?
Where do you think the main code lives?
Where do you think tests live, if there are any?

Do not worry about being correct. You are making a prediction before the agent helps.

Checkpoint A¶

You are ready to continue when you can say:

"I have a rough guess about what this project is and where the important files are."

Part B: Start OpenCode in the Project¶

Make sure your terminal is inside the project folder:

pwd

The printed path should be the repo you chose for this lab.

Start OpenCode:

opencode

You should see the OpenCode TUI with an input box at the bottom.

If OpenCode opens in build mode, press Tab to switch to plan mode.

Checkpoint B¶

You are ready to continue when: - OpenCode is open. - You are inside the project folder. - You know whether you are in plan mode or build mode.

Part C: Run `/init`¶

In the OpenCode input box, type:

/init

Press Enter.

OpenCode will inspect the project and generate or update AGENTS.md.

Depending on the project size and model speed, this may take a minute. Watch what the agent reads. It may inspect files such as README.md, package files, config files, or test directories.

When it finishes, exit OpenCode:

exit

If exit does not close the TUI, press Ctrl+C.

Now check that AGENTS.md exists:

ls AGENTS.md

Checkpoint C¶

You are ready to continue when: - AGENTS.md exists in the project root. - You know that this file was generated from the agent's inspection, not from magic.

Part D: Read `AGENTS.md` Like a Human Reviewer¶

Open AGENTS.md in your editor or read it in the terminal.

As you read, mark each section with one of these labels:

Label	Meaning
`Clear`	The instruction is specific and useful.
`Vague`	The instruction sounds right but does not give enough detail.
`Wrong`	The instruction contradicts the project files.
`Risky`	The instruction might let the agent do too much.

Look for these common sections: - Project context. - Key directories. - Build or run commands. - Test commands. - Style or formatting conventions. - Git or commit expectations. - Out-of-bounds actions.

Example Review Notes¶

Your notes might look like this:

Project context: Clear. It correctly says this is a Python CLI tool.
Key directories: Clear. src/ and tests/ both exist.
Test command: Vague. It says "run tests" but does not name pytest.
Out of bounds: Risky. It does not say anything about not editing generated files.

Do not edit AGENTS.md yet. First, practice reading it critically.

Checkpoint D¶

You are ready to continue when you have at least five review notes about AGENTS.md.

Part E: Ask OpenCode to Explain Its Own Instructions¶

Start OpenCode again if you exited:

opencode

In plan mode, ask:

Read AGENTS.md and explain the project conventions to me as if I am new to this repo. Do not edit any files.

Compare the explanation to your own notes.

Then ask one follow-up question:

Which parts of AGENTS.md are based on direct evidence from files in this repo, and which parts look like guesses?

This is an important habit. Agents often sound confident even when they are guessing. Your job is not to distrust everything. Your job is to ask, "What evidence supports this?"

Checkpoint E¶

You are ready to continue when you can identify at least one instruction that was clearly evidence-based and one instruction that may have been guessed.

Part F: Explain the Project Conventions Yourself¶

Now write a short explanation in your own words. Use this structure:

Project name:

What this project appears to do:

Main folders and files:

How to run or test it, if known:

Style or naming conventions:

Things the agent should avoid:

One thing AGENTS.md got right:

One thing AGENTS.md should explain better:

Keep it short. One or two sentences per line is enough.

Success Criteria¶

You have completed this lab when: 1. You ran opencode from inside a real project folder. 2. You ran /init successfully. 3. The project has an AGENTS.md file in its root. 4. You read AGENTS.md instead of assuming it was correct. 5. You wrote at least five review notes using Clear, Vague, Wrong, or Risky. 6. You asked OpenCode to explain which parts were evidence-based and which parts were guesses. 7. You wrote your own plain-English summary of the project conventions.

Troubleshooting¶

Issue	What to Try
`opencode: command not found`	Return to Lab 2.1 and verify OpenCode is installed and on your `$PATH`.
OpenCode says no API key is configured	Check that `ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, or your Ollama setup is configured.
`/init` does not create `AGENTS.md`	Confirm you ran OpenCode from the project root. Exit, run `pwd`, then start OpenCode again.
The agent wants to edit many files	Stop. For this lab, only `AGENTS.md` should be created or updated. Stay in plan mode unless instructed otherwise.
The generated file is extremely long	You may have chosen a repo that is too large. Use a smaller project and try again.
The generated file is very generic	Ask the agent what files support each instruction. If it cannot point to evidence, mark that section `Vague`.
You do not understand a command listed in `AGENTS.md`	Do not run it yet. Ask OpenCode to explain what the command does in plan mode.

Reflection Prompts¶

Answer these before moving to the Week 2 reflection file:

What did /init correctly understand about the project?
What did /init miss, oversimplify, or get wrong?
Which instruction in AGENTS.md would help prevent a bad agent action?
Which instruction in AGENTS.md is too vague to be useful?
If a new teammate joined this project, would AGENTS.md help them? Why or why not?

What's Next?¶

In the Week 2 reflection, you will compare your Lab 2.1 and Lab 2.2 experiences.

The key question is:

When did the agent get something wrong, and what clue helped you notice?

That question matters for the rest of the course. OpenCode is powerful, but your judgment is still part of the system.

Lab 2.2: Run /init and Explain AGENTS.md¶