diff --git a/content/img/open_code.png b/content/img/open_code.png new file mode 100644 index 0000000..4ed3016 Binary files /dev/null and b/content/img/open_code.png differ diff --git a/content/scenario-agentic.md b/content/scenario-agentic.md index 19b706e..134523d 100644 --- a/content/scenario-agentic.md +++ b/content/scenario-agentic.md @@ -1,9 +1,9 @@ # Scenario III: Full Agentic Code Development - + :::{questions} - What are agentic coding tools and how do they differ from other approaches? - What risks come with giving an AI agent access to your system? @@ -31,90 +31,102 @@ on the level of automation, you might not even see any of the code that is gener :width: 100% ``` - -### Why this is the highest-risk approach +:::{admonition} Why this is the highest-risk approach +:class: dropdown 1. **Autonomous execution**: Agent runs commands without per-command approval 2. **System access**: May have access to your shell, files, network 3. **Opaque decision-making**: Hard to predict what the agent will do 4. **Irreversible actions**: Deleted files, pushed commits, installed packages - +::: ## Landscape of agentic coding tools There are a few options to go fully agentic. The level of risk can be proportional to the performance of the AI model, with larger proprietary models performing better than smaller ones. This means that a paid subscription is needed to use powerful remote AI models. -:::{warning} -To-Do: This section needs expanding with the recent Claude code + Ollama + local LLMs. -::: - -### Claude Code (Anthropic) +### OpenCode -[Claude code](https://code.claude.com/docs/en/overview) is a terminal-based agent that lives in your shell. +[OpenCode](https://opencode.ai/), an open-source terminal-based coding +agent. -```{figure} img/claude_code.png -:alt: Claude code +```{figure} img/open_code.png +:alt: OpenCode :width: 100% -A screenshot to show how the Claude code command line interface (CLI) looks like. +A screenshot to show how the OpenCode command line interface (CLI) looks like. ``` - - **Capabilities:** -- Reads and writes files in your project -- Executes shell commands -- Understands git workflows -- Can work across multiple files -- It can also be integrated to VScode or other IDEs. +- read and write project files +- execute shell commands +- install packages +- work across multiple files +- use different AI model providers **Safety features:** -- Asks for permission before potentially dangerous operations -- Shows proposed changes before applying - -:::{admonition} Claude Code: Beginner Cheatsheet +- Review the agent's plan before allowing it to make changes. +- OpenCode can read and write files and run shell commands, so only give it + access to the files and environment you intend to use. +- For demonstrations and experiments, consider running OpenCode inside a + sandbox such as Docker. +- Avoid running agentic tools with access to production systems, secrets, or + sensitive credentials. + +:::{admonition} OpenCode: Beginner Cheatsheet ## Before anything: security mindset -- Claude Code can **read, write, delete files and run shell commands** on your machine +- OpenCode can **read, write, delete files and run shell commands** on your machine - By default it asks permission at each step — **do not skip this** - Always work inside a **git repo** so you can undo (`git diff`, `git restore`) - Never run it on production systems or with credentials in your environment -## Human-in-the-loop: plan mode first ([docs](https://code.claude.com/docs/en/planning)) +## Human-in-the-loop: plan mode first ([docs](https://opencode.ai/docs/)) -- Press `Shift+Tab` to enter **plan mode** before Claude does anything -- Claude reads your codebase, drafts a step-by-step plan, then **stops and waits** +- Press `Tab` to enter **plan mode** before OpenCode does anything +- OpenCode reads your codebase, drafts a step-by-step plan, then **stops and waits** - You review, edit, or reject the plan before any file is touched - This is the recommended default for beginners — **always plan before you execute** -## Key built-in slash commands ([docs](https://code.claude.com/docs/en/overview)) +## Key built-in slash commands ([docs](https://opencode.ai/docs/tui/?utm_source=chatgpt.com)) +- `/connect` — connect a model provider +- `/init` — initialize project instructions in AGENTS.md +- `/undo` and `/redo` — undo/redo agent changes +- `/share` — share a conversation +- `/help` — show commands +- `/exit` — quit OpenCode -- `/clear` — wipe the conversation, start fresh (saves tokens) -- `/compact` — compress context when the window fills up -- `/memory` — edit your `CLAUDE.md` on the fly -- `/model` — switch between Opus / Sonnet / Haiku mid-session -- `/cost` — see how many tokens you've spent +## How OpenCode remembers things: three layers ([docs](https://opencode.ai/docs/rules/)) -## How Claude remembers things: three layers ([docs](https://code.claude.com/docs/en/memory)) +- **`AGENTS.md`** — persistent project guidance; coding standards, build commands, architecture notes, and team conventions. Put it in the repo root and commit it. +- **Instructions** (opencode.json) — additional instruction sources for more specialized project guidance. Useful for keeping the main AGENTS.md focused. ([docs](https://opencode.ai/v2/docs/instructions)) +- **Skills** (`.opencode/skills//SKILL.md`) — reusable procedures OpenCode can discover and load when relevant, such as releases, migrations, testing, or code review. ([docs](https://opencode.ai/docs/skills/)) -- **`CLAUDE.md`** — always loaded; project-wide standards, build commands, coding style. Think of it as the employee handbook Claude reads on day one. Put it in the repo root and commit it. -- **Rules** (`.claude/rules/`) — loaded only when path matches; domain-specific constraints (e.g. a database rule that only activates when editing `*.sql` files). Good for keeping context lean. -- **Skills** (`.claude/skills//SKILL.md`) — reusable procedures Claude can invoke automatically based on context, or you can call with `/skillname`. Share them across projects or with your team. +## Subagents — keeping context clean ([docs](https://opencode.ai/docs/agents/)) -## Subagents — keeping context clean ([docs](https://code.claude.com/docs/en/sub-agents)) +- OpenCode can launch subagents in separate child sessions with fresh context +- They handle focused research/search tasks and return results — keeping the main agent’s context cleaner +- Built-in subagents include **Explore** and **General** +- Permissions can be configured per agent — subagents are **not** a security boundary -- Claude can spin up isolated sub-instances with their own context window -- They do the messy reading/searching and return a distilled result — your main thread stays focused -- Built-in: **Explore** (read-only codebase search), **Plan** (strategy before writing) -- Still subject to the same permissions — subagents are **not** a security boundary - -## Context window tips +## Context window tips ([docs](https://opencode.ai/docs/tui/)) - Use `/compact` when context fills up, `/clear` between unrelated tasks -- `@filename` to include specific files rather than letting Claude scan everything +- `@filename` to include specific files directly in context - `!command` to inject shell output directly into context ::: -:::{exercise} Demo: Iris dataset analysis with Claude Code +## Sandboxing and permission control + +- Coding with agentic agents can potentially affect more of the system than intended. + +- Sandboxing means running the agent inside an isolated environment with limited +access to the host computer. For example, a Docker container can expose only +the project directory that the agent needs. + +:::{exercise} Demo: Iris dataset analysis with OpenCode +in this excersize we consider two setups: + +1. **Without sandboxing** — OpenCode runs directly on the local machine and + can use the tools and files available to the current user. ## Setup: project folder and environment ```bash cd agentiris @@ -122,10 +134,50 @@ mamba create python=3.11 -p ./env ``` ```bash conda activate ./env -claude +curl -fsSL https://opencode.ai/install | bash ``` +```bash +opencode +``` +2. **With sandboxing** — OpenCode runs inside a Docker container with access + only to the project directory and the tools installed in that container. -## In Claude Code: switch to plan mode first +The non-sandboxed setup is simpler, while the sandboxed setup provides better +isolation and more control over what the agent can access. +## Setup: project folder and environment +```bash +cd agentiris + +cat > Dockerfile <<'EOF' +FROM python:3.11-slim + +RUN apt-get update && apt-get install -y \ + curl \ + git \ + make \ + && rm -rf /var/lib/apt/lists/* + +RUN curl -fsSL https://opencode.ai/install | bash + +ENV PATH="/root/.opencode/bin:$PATH" + +WORKDIR /project +EOF +``` +```bash +docker build -t irisagent-demo . + +docker run -it --rm \ + -p 8000:8000 \ + -v "$(pwd):/project" \ + -w /project \ + irisagent-demo bash +``` +```bash +opencode +``` + +## In OpenCode: switch to plan mode first Press `Shift+Tab` to enter **plan mode**, then paste this prompt: ``` @@ -145,7 +197,7 @@ running inside a mamba environment so you can use mamba install to add packages that are missing. ``` -- Claude will **read your environment, draft a plan, and stop** +- OpenCode will **read your environment, draft a plan, and stop** - Review the plan before pressing Enter to approve - Only then will it start creating files and running code @@ -160,12 +212,14 @@ results and any figures produced, and structure it as a readable scientific report. ``` -- Claude will wire up Sphinx, write the `.rst` source files, and link the figures from `results/` +- OpenCode will wire up Sphinx, write the `.rst` source files, and link the figures from `results/` - Review the plan — Sphinx setup touches several config files - After approval, you can build the docs with `make html` inside `docs/` ::: +## More agentic tools +[Claude code](https://claude.com/) and [Codex](https://openai.com/codex/) are the OpenAI alternative to OpenCode, which need subscriptions. :::{admonition} Practitioner's perspective: A real Claude Code session :class: tip @@ -200,24 +254,28 @@ Key observations: Even experienced practitioners reach points where they need to take over. ::: -### OpenAI Codex - -[Codex](https://openai.com/codex/) is the OpenAI alternative to Claude code. - ### Other tools - + | Tool | Type | Key Characteristic | |------|------|-------------------| | Aider | Terminal | Open source, multiple model support | -| GitHub Copilot Workspace | Web | PR-centric workflow | +| GitHub Copilot coding agent | Web | PR-centric workflow | | Continue | IDE extension | Open source, customizable | +| Claude Code | Anthropic | CLI-based, git integration, sandboxing | +| OpenAI Codex | OpenAI | CLI-based, git integration, sandboxing | +| Gemini CLI | Google | Multimodal, Google integration | +| Cursor | Cursor Inc. | AI-native IDE with agent mode | +| Cline | Cline | IDE/CLI agent, file editing, command execution, multiple models | +| Devin | Cognition | Autonomous software engineer, testing, debugging, pull requests | +| OpenHands | Open source | Autonomous coding agent, terminal and repository interaction | -## What can possibly go wrong? +::::{admonition} What can possibly go wrong? +:class: dropdown Agentic tools can cause serious problems if not properly supervised. @@ -288,6 +346,7 @@ this attack surface significantly. - generated low quality PRs cost maintainers of open source projects time. (e.g. [PR of a lazy agent](https://github.com/JuliaPlots/Plots.jl/pull/5728)) - Agents may interact with other humans in inappropriate ways (e.g. [agent writing a hitpiece because its PR got closed](https://github.com/matplotlib/matplotlib/pull/31132)) +:::: ## Permission models and controls @@ -491,11 +550,11 @@ blind trust in either direction. ## Exercises - + :::{exercise} Exercise Agent-1: Explore an agent (read-only) If you have access to an agentic tool (Claude Code, Cursor, etc.): @@ -599,6 +658,7 @@ tasks, with what safeguards, and how much supervision?" ## See also +- [OpenCode Documentation](https://opencode.ai/en/docs) - [Claude Code Documentation](https://docs.anthropic.com/claude/docs/claude-code) - [Docker Security Best Practices](https://docs.docker.com/develop/security-best-practices/) - [Bubblewrap (sandboxing tool)](https://github.com/containers/bubblewrap) diff --git a/content/scenario-full-control.md b/content/scenario-full-control.md index dddee99..6e4fdeb 100644 --- a/content/scenario-full-control.md +++ b/content/scenario-full-control.md @@ -25,13 +25,14 @@ and your development environment. :width: 100% ``` -### Why this is the lowest-risk approach +:::{admonition} Why this is the lowest-risk approach +:class: dropdown 1. **You see everything**: Every piece of code goes through your eyes and clipboard 2. **Nothing runs automatically**: You decide when and how to execute code 3. **Clear boundaries**: The AI cannot access your files, run commands, or modify anything 4. **Explicit data sharing**: You control exactly what context the AI receives - +::: ## What information leaves your machine? @@ -76,8 +77,8 @@ When starting a project or evaluating approaches, use the AI for research: "What approaches could I use for parallelizing this computation?" -"What are some useful drag-and-drop libraries in JavaScript? -Build me an example demonstrating each one." +"What are some useful drag-and-drop libraries in JavaScript? +"Build me an example demonstrating each one. ``` This helps you understand the landscape before committing to an approach. @@ -168,12 +169,12 @@ text in your conversation that influences the AI's responses. ## Effective prompting strategies -The quality of AI-generated code depends heavily on how you ask for it. - +The quality of AI-generated code depends heavily on how you ask for it. For coding tasks, effective prompting is usually an iterative process: define the task clearly, provide relevant context and constraints, generate a manageable piece of code, test the result, and refine the prompt based on what you observe. + ### Strategy 1: Start with architecture, not implementation Instead of asking for 500 lines of code at once, begin with structure: @@ -197,7 +198,7 @@ Instead of asking for 500 lines of code at once, begin with structure: Help the AI understand your constraints: -``` +```text I'm working on: - Python 3.11 - Ubuntu 22.04 @@ -219,6 +220,7 @@ Write a function to perform bootstrap resampling. Please: ### Strategy 4: Iterate incrementally + After each step, run or test the generated code before moving on. If something fails, include the error message, failing input, or unexpected output in the next prompt. ``` Session flow: 1. "Write a function to load CSV data with error handling" @@ -244,7 +246,7 @@ The first response is rarely the final answer. Use follow-up prompts freely: - "Break that repetitive code out into a function" - "Use string manipulation methods rather than a regular expression" -- "Write that better!" +- "improve the readability and structure while keeping the same behavior!" - "Now write tests for this using pytest" - "Can you explain what line 15 does?" @@ -590,12 +592,14 @@ transparency support reproducibility and scientific integrity. ## See also - + - [Prompting Guide](https://www.promptingguide.ai/) - General prompting techniques - [Google: Best Practices for AI Coding Assistants](https://cloud.google.com/blog/topics/developers-practitioners/five-best-practices-for-using-ai-coding-assistants) - [Simon Willison: How I use LLMs to help me write code](https://simonwillison.net/2025/Mar/11/using-llms-for-code/) - Detailed practical workflow - [Zero To Mastery: How to Use ChatGPT to 10x Your Coding](https://zerotomastery.io/blog/how-to-use-chatgpt-for-coding/) - Prompt engineering techniques - +- [Prompt engineering best practices for ChatGPT](https://help.openai.com/en/articles/10032626-prompt-engineering-best-practices-for-chatgpt) +- [GitHub Copilot Prompt Engineering](https://docs.github.com/en/copilot/concepts/prompting/prompt-engineering) +- [GitHub Copilot Writing Tests](https://docs.github.com/en/copilot/tutorials/write-tests) :::{keypoints} - Chat-based AI coding gives you maximum control over data and execution diff --git a/content/scenario-ide-integration.md b/content/scenario-ide-integration.md index 3d41671..99f7fa4 100644 --- a/content/scenario-ide-integration.md +++ b/content/scenario-ide-integration.md @@ -70,11 +70,11 @@ Each tool has different data collection policies. For example: ## Setting up GitHub Copilot - + GitHub Copilot is currently the most widely-used IDE-integrated assistant. Here's how to set it up with privacy and control in mind. @@ -160,7 +160,9 @@ Some tools (like Cursor, Copilot Workspace) can: - Apply changes across your codebase - Suggest refactoring patterns -:::{callout} Increased risk with automated edits +:::{admonition} Increased risk with automated edits +:class: dropdown + When tools can modify multiple files: - Changes may have unintended consequences - Harder to review all modifications @@ -201,18 +203,19 @@ Some developers find it faster to: This works but requires discipline. Don't skip step 2. -## Alternative tools: Windsurf +## Alternative tools: -GitHub Copilot isn't your only option. Here's how alternatives compare: +GitHub Copilot isn't your only option. [JetBrains AI Assistant](https://www.jetbrains.com/help/ai-assistant/code-completion.html), [Tabnine](https://www.tabnine.com/), and [Windsurf Plugin](https://docs.devin.ai/windsurf/plugins/getting-started) (previously Codeium) offer different trade-offs in terms of privacy, features, and pricing. +Here's how alternatives compare: -### Windsurf (previously known as Codeium) +### Windsurf Plugin - **Pricing**: Free core features - **Privacy**: Claims no training on your code - **Features**: 70+ languages, chat interface, Windsurf IDE Setup in VS Code: -1. Install ["Windsurf" extension](https://marketplace.visualstudio.com/items?itemName=Codeium.codeium) +1. Install [Windsurf plugin](https://docs.devin.ai/windsurf/plugins/getting-started) 2. Create account at windsurf.com 3. Authenticate in VS Code @@ -251,7 +254,7 @@ For many applications, using a well-tested library (like Python's ::: -:::{exercise} Exercise IDE-3: Context awareness experiment +:::{exercise} Exercise IDE-2: Context awareness experiment Test what context your AI tool uses: 1. Open two Python files in VS Code: