Skip to content

Latest commit

 

History

History
370 lines (240 loc) · 16 KB

File metadata and controls

370 lines (240 loc) · 16 KB

Week 1 Lab — Coding Agents

Repository Guide | English | 한국어

Last Updated: 2026-11-18

Learning Objectives:

  1. Install and authenticate a coding agent such as Gemini CLI or Claude Code
  2. Delegate real tasks to an agent and critically evaluate its output
  3. Apply the RALPH technique to iteratively improve agent-generated work
  4. Understand how a minimal OS is structured (bootloader, kernel, linker script)

Table of Contents



1. Lab Overview

  • Objective: Install AI-based coding agents and use them in real development tasks.
graph LR
    T1["Task 1<br/>Install Agent"] --> T2["Task 2<br/>File Organization"]
    T2 --> T3["Task 3<br/>Repo Documentation"]
    T3 --> T4["Task 4<br/>RALPH Technique"]
    T4 --> T5["Task 5<br/>Mini OS Build"]
Loading

Figure 1. Order of lab tasks 1-5



2. The Concept of a Coding Agent

A coding agent is an AI-based CLI tool that generates code by understanding context.

graph LR
    A["Read<br/>Files & Context"] --> B["Plan<br/>Decide what to do"]
    B --> C["Execute<br/>Edit & Run"]
    C --> D["Verify<br/>Check results"]
    D -->|Iterate| A
    style A fill:#e3f2fd
    style B fill:#fff3e0
    style C fill:#e8f5e9
    style D fill:#fce4ec
Loading

Figure 2. The read, plan, execute, and verify loop of a coding agent

  • It can read the file system, execute commands, and make edits autonomously.
  • It is used for scaffolding, refactoring, documentation, and debugging.

Scaffolding refers to automatically generating a project's initial skeleton (directory structure, configuration files, boilerplate code, etc.). The term originates from the construction industry, where scaffolds are erected before building. For example, if you say "Create a React project," the agent will create package.json, a src/ directory, basic component files, and more all at once.

Example: Given the request "Write a Makefile for a C project with debug and release targets", the agent works in the order: checks directory → writes Makefile → verifies build success.

Key Point: Unlike simple code autocompletion tools (such as Copilot), coding agents are autonomous tools that can understand the entire project context, read and modify multiple files simultaneously, and execute commands. The key difference from a ChatGPT web interface is that they directly access the local file system to perform tasks.



3. Available Agents

Agent Price Description
Gemini Gemini CLI Free (1,000 requests/day) Google's agent. A good default choice.
Claude Claude Code Paid Anthropic's agent. Powerful multi-file reasoning capabilities.
OpenAI Codex CLI Paid OpenAI's agent. An open-source CLI.

Table 1. Price and characteristics of the available coding agents

Another option is OpenCode. OpenCode is an open-source harness that can use a wide range of models, including open-source LLMs.

Gemini CLI is free and can be used without cost concerns for lab exercises. Claude Code excels in complex multi-file projects, and Codex CLI is open-source and customizable. We recommend starting with the free Gemini CLI and trying other agents as needed.



4. Task 1: Install a Coding Agent

Refer to the official documentation and install at least one coding agent.

Installation commands:

npm install -g @google/gemini-cli           # Gemini CLI (free)
npm install -g @anthropic-ai/claude-code    # Claude Code (paid)

Verify installation:

gemini --version    # or: claude --version

Checklist:

  • Check that the CLI runs without errors.
  • Check that you can authenticate (Gemini uses a Google account, Claude uses an Anthropic account).
  • Enter a simple prompt such as "What is 2 + 2?" and check that a response is returned.

npm is the package manager for Node.js. If it is not installed, you must first install the LTS version from the official Node.js website. After installation, you can verify it by running node --version and npm --version in the terminal.

The -g in npm install -g stands for global, meaning the package is installed system-wide rather than in the current project. With a global installation, you can run commands like gemini or claude directly from any terminal location. Without -g, the package is installed only in the current directory's node_modules/ and cannot be used as a global command.



5. Task 2: File Organization

Use an agent to organize files in a messy directory.

Example prompt:

"Organize the files in ~/Downloads into subdirectories by file type
 (images, documents, code, etc.). Show me the plan before executing."

What to observe:

  • Does the agent ask for confirmation before moving files?
  • Does it create a reasonable folder structure?
  • Does it handle edge cases well (e.g., files without extensions)?

Discussion:

  • What would have happened if you had not said "Show me the plan first"?
  • How can you give more specific instructions when the result is unsatisfactory?

Getting into the habit of asking the agent to "Show me the plan first" when delegating tasks is very important. This prevents unintended file deletion or movement. Especially when working with real file systems, undo is difficult, so it is safest to always review and approve the agent's plan before execution.



6. Task 3: GitHub Repository Documentation

Use an agent to generate a README.md for an existing codebase.

Choose a target repository:

  • Use your own project or a public repository such as the following.
    • https://github.com/code-yeongyu/oh-my-opencode

Example prompt:

"Read this codebase and write a comprehensive README.md that includes
 an architecture overview, installation instructions, and usage examples."

Evaluate the result:

  • Does the README accurately describe the project?
  • Are the installation instructions correct and complete?
  • Is anything missing (license, contribution guide, screenshots)?

Save this README, because the next task (Task 4) improves it.



7. Task 4: The RALPH Technique

Definition: A rubric is a structured set of criteria used to evaluate the quality of a deliverable.

Create a verifiable evaluation rubric and use it to iteratively improve the quality of the output.

Figure 3. Ralph Wiggum, the character that symbolizes the RALPH technique

Figure 3. Ralph Wiggum, the character that symbolizes the RALPH technique

Request → Analyze → List issues → Prompt again → Harmonize

Step-by-step process:

  1. Ask the agent to generate a rubric (e.g., "What makes a world-class README?").
  2. Ask the agent to evaluate its own output against the rubric.
  3. Ask it to fix all identified issues.
  4. Repeat until all criteria are met.

Key phrases to try:

  • "Keep going until all criteria are met"
  • "Evaluate against the rubric and fix all issues"

Key Point: The RALPH technique is a methodology for systematically improving AI agent output. The core idea is to have the agent create its own evaluation criteria, evaluate its own output against those criteria, and then fix any deficiencies. Repeating this loop yields results of much higher quality than the initial output.

7.1 Applying RALPH in Practice

Example workflow using the README from Task 3:

You:   "Create a rubric for evaluating a high-quality open-source README."
Agent: Returns 8 criteria (description, installation, usage, architecture, ...)

You:   "Evaluate the README you wrote against this rubric. Score each criterion."
Agent: 6/8. Not met: architecture diagram, contribution guide.

You:   "Fix all unmet criteria. Add an architecture diagram and a contribution guide."
Agent: Updates README with both additions.

You:   "Evaluate again. Are all criteria met?"
Agent: 8/8. All criteria met.

Why this matters:

  • Agents produce decent results on the first try, but they are not perfect.
  • The RALPH loop teaches you how to systematically improve agent output.
  • This technique applies not only to coding agents but to all AI tools.


8. Task 5: Build a Mini OS

Use an agent to create a minimal operating system.

Example prompt:

"Create a minimal bootable OS for x86. It should print 'Hello, OS!' to the screen.
 Include a Makefile and instructions for running it in QEMU."

Expected output files:

graph LR
    A["boot.asm<br/>Bootloader"] --> B["kernel.c<br/>Main Kernel"]
    B --> C["linker.ld<br/>Memory Layout"]
    C --> D["Makefile<br/>Build System"]
    style A fill:#e3f2fd
    style B fill:#fff3e0
    style C fill:#e8f5e9
    style D fill:#fce4ec
Loading

Figure 4. Expected output files of the mini OS build and the role of each file

Because a powered-on x86 CPU starts in real mode, in which it can access only 1 MB of memory, a step that switches the CPU to protected mode, which enables full memory access and hardware protection features (such as memory segmentation and privilege levels), is needed before the kernel runs. In Figure 4, boot.asm performs this step.

Definition: Bootloader. The program that loads the kernel into memory and switches the CPU from real mode to protected mode. A 32-bit kernel can run only after this switch is complete.

[Computer Architecture] With legacy BIOS booting, when a computer is powered on, the BIOS loads the boot sector (512 bytes) into memory and executes it (UEFI loads an EFI executable instead of a boot sector). boot.asm is this boot sector code, which starts in Real Mode, transitions to Protected Mode, and then loads the kernel (kernel.c). linker.ld is a linker script that specifies where the kernel code and data are placed in memory.

For regular applications, the OS manages memory layout, but when developing an OS itself, you must specify where the code is loaded in memory yourself. The linker script is what performs this role. For example, the bootloader must be located at memory address 0x7C00, and the kernel code must be placed at the address where the bootloader loads it; this is specified in the linker script through the starting addresses and ordering of .text, .data, and .bss sections. .text holds executable code, .data holds initialized variables, and .bss holds uninitialized variables. 0x7C00 is the memory address where the BIOS places the boot sector, a convention established decades ago by the IBM PC BIOS. Without a linker script, the linker would use its default layout for regular applications and booting would fail.

8.1 What to Observe

You do not need to successfully boot the OS. The process is what matters.

Observe how the agent:

  • Decomposes a complex problem into multiple files
  • Explains the role of each component
  • Handles errors when given feedback
  • Iteratively fixes build failures

Follow-up prompts to try:

  • "Add keyboard input support"
  • "Explain what the linker script does, line by line"
  • "The build failed with error X. Fix it"

It is highly likely that the OS code generated by the agent will produce build errors when run as-is. In that case, pass the error message directly to the agent. The key is to be specific: "The build failed. Here is the error message: [error message]."

Key Point: Coding agents are just tools, and understanding the output they generate is still the user's own responsibility.

It is important to view agents as powerful assistants, not magic tools. If you submit agent-generated code without understanding it, there is no learning benefit. Always ask "Explain why you did it this way," and develop the habit of reading and understanding the generated code yourself.



Glossary

English Korean One-Line Definition
LTS (Long-Term Support) LTS In Node.js, the stable, long-term support version recommended for most users.
Real Mode 리얼 모드 The mode an x86 CPU runs in when it first starts, in which the CPU can access only 1 MB of memory.
Protected Mode 프로텍티드 모드 The x86 CPU operating mode that enables full memory access and hardware protection features (such as memory segmentation and privilege levels).

Table 2. Glossary



Summary

Concept Key Summary
Agent installation (Task 1) You set up the tool, authenticate, and check that it works with a basic prompt.
File organization (Task 2) You delegate a real task to the agent and review its decisions.
Repository documentation (Task 3) You evaluate AI-generated technical documentation for accuracy and completeness.
RALPH technique (Task 4) You use a rubric to improve the output systematically and iteratively.
Mini OS (Task 5) You work with the agent on a complex system project made of multiple files.


Self-Check Questions

  1. What is the key difference between a coding agent and a simple code autocompletion tool like Copilot?

    Answer

    Copilot autocompletes a single code fragment at the cursor. A coding agent invokes multi-step tools (read/write files, build, test, run commands) and autonomously plans, executes, and verifies work against a goal. Agents operate on the entire project state, not a single line.

  2. Why is it important to ask an agent to "Show me the plan first" before executing file system operations?

    Answer

    File-system actions can be irreversible (deletes, overwrites). If the agent misunderstands intent, the damage is hard to undo. Reviewing the plan first lets the user catch scope errors (wrong paths, unintended deletes) before any disk change is made.

  3. Describe the RALPH technique in your own words. Why does iterating with a rubric produce better results than a single prompt?

    Answer

    RALPH (Request, Analyze, List issues, Prompt again, Harmonize) defines explicit evaluation criteria (a rubric), then has the agent produce, self-evaluate against the rubric, and revise iteratively. A single prompt relies on one guess; a rubric-driven loop steers each revision toward measurable criteria, so the output quality converges rather than drifting.

  4. When building a mini OS, what is the role of the bootloader, and why must it switch from Real Mode to Protected Mode?

    Answer

    The bootloader is the tiny program the firmware runs first; it loads the kernel into memory and transfers control. On x86, Real Mode is 16-bit and limited to 1 MB addressing. Any modern kernel needs 32-bit or 64-bit addresses and memory protection, so the bootloader must enable Protected Mode before jumping to the kernel.

  5. If the agent-generated OS code fails to build, what is the most effective way to ask the agent to fix it?

    Answer

    Feed back the full error output, the exact command that failed, and the environment (OS, compiler version). Define a clear success condition (e.g., "fix this error and keep existing tests passing"). The more concrete the context, the less the agent has to guess at the root cause.