Have you ever built a web app with React but felt lost about where to even start with a mobile app? With React Native, you can build iOS/Android apps using the same React syntax you already know. But when you actually try to get started, you run into barriers like Xcode, Android Studio, and native build configuration.

The thing that almost completely removes these barriers is Expo. In this article, we'll set up a development environment with Expo and build a simple Todo app from start to finish. The features we'll build are:

• Add a task / toggle completion / delete
• Persist data so the list survives even after closing and reopening the app

This article targets readers familiar with React (components, JSX, useState), and focuses on "how to develop with Expo" rather than React syntax itself. You can find the complete code in the GitHub repository.

The environment is based on macOS, and assumes the Node.js LTS version is installed.

2. What Is Expo? Why Expo?

React Native is a framework that renders code written in JavaScript/TypeScript as actual native UI. In other words, it produces a real native app, not an app faked with a webview.

The problem is that to start with pure React Native, you have to install Xcode and Android Studio and configure the native build environment yourself. For beginners, this initial setup alone is the biggest wall.

Expo is a collection of tools and services layered on top of React Native that dramatically lowers this wall.

• Start without a native build environment: you can create a project and run it immediately with a single command
• Expo Go: if you install the Expo Go app from the App Store/Play Store, you can scan a QR code and instantly launch your app on your phone. No separate build needed
• Rich SDK: you can use native features like camera, location, notifications, and local storage just by installing a package
• EAS Build: later, when you want to build a real app and publish it to the stores, you can use the cloud build service

The relationship between your code and the runtime environment looks like this in a diagram.

flowchart TD
    A["My code (TypeScript / JSX)"] --> B["Expo (CLI · SDK · Expo Go)"]
    B --> C["React Native"]
    C --> D["iOS native"]
    C --> E["Android native"]

We write code in App.tsx, and Expo connects it to React Native and renders it as each platform's native screen.

3. Getting Started: From Project Creation to Running

First, check whether Node is installed.

node -v

Now create a project with create-expo-app. Here we use the blank TypeScript template.

npx create-expo-app@latest my-todo-app --template blank-typescript

Expo's default template includes file-based routing (Expo Router) and tab navigation, which is a bit heavy for beginners. So we chose the blank-typescript template that starts with a single empty screen. We'll only touch on Expo Router as a keyword in Section 7.

Once creation is done, move into the project folder and start the development server.

cd my-todo-app
npx expo start

A QR code and a run-options menu appear in the terminal. Pick the one that fits your situation.

• Expo Go (easiest): install the Expo Go app on your phone and scan the QR code in the terminal
• i: run on the iOS simulator (requires macOS + Xcode)
• a: run on the Android emulator (requires Android Studio)
• w: run in a web browser

When it runs, you'll see the default screen that says "Open up App.tsx to start working on your app!". If you've made it this far, your development environment is ready.

The terminal displays a QR code and a key-shortcut menu similar to the following. Seeing this screen means the development server has started successfully.

Below the QR code, the following guidance and shortcut menu are also shown.

› Metro waiting on exp://192.168.0.10:8081
› Scan the QR code above with Expo Go (Android) or the Camera app (iOS)

› Press s │ switch to development build
› Press a │ open Android
› Press i │ open iOS simulator
› Press w │ open web

› Press r │ reload app
› Press m │ toggle menu
› Press ? │ show all commands

The exp://... address is the location where the Metro bundler is running, and your phone's Expo Go app connects to this address to download and run the app bundle. On iOS, scan the QR above with the default Camera app; on Android, scan it with the scanner inside Expo Go, and the app launches on your phone right away. For the simulator/emulator/web, press the i/a/w keys respectively.

What If You Don't Have an iOS Simulator?

The iOS simulator only works with macOS + Xcode. If you don't have Xcode, use Windows/Linux, or find the installation burdensome, you can run the app perfectly fine without a simulator.

• Real device + Expo Go (most recommended): install the Expo Go app on your phone and scan the QR code from npx expo start. On iOS, scan with the default Camera app; on Android, scan with the scanner inside Expo Go. Your PC and phone must be on the same Wi-Fi, and if a corporate network or similar prevents the connection, you can work around it with npx expo start --tunnel
• Web browser: with npx expo start --web (or the w key), you can check it immediately without any installation. The Todo app we'll build also works on the web, where AsyncStorage is handled as the browser's localStorage, so the list persists even after a refresh. There may, however, be subtle differences from a real mobile device
• Android emulator: if you have Android Studio, you can create an AVD and run it with the a key

If you really want to use the iOS simulator, install Xcode from the Mac App Store, then download the iOS simulator runtime from Xcode → Settings → Components (or Platforms) and press the i key in npx expo start.

If you just want to quickly check the screen, use web; if you need a real mobile feel, a real device + Expo Go is recommended. Installing the iOS simulator is optional.

4. Looking at the Project Structure

Let's look at only the core files of the generated project.

my-todo-app/
├── App.tsx          # The app's entry point. Where the screen is drawn
├── app.json         # Expo settings such as app name, icon, splash
├── package.json     # List of dependencies
├── tsconfig.json    # TypeScript settings (extends expo/tsconfig.base)
└── assets/          # Resources such as icons and splash images

The one place where we'll spend almost all our time is the single file App.tsx. Like the web's index.html or a root component, this component is the first thing drawn on the screen when you open the app.

One more thing: Expo supports Fast Refresh. When you edit and save App.tsx, the changes are immediately reflected on the screen without needing to restart the app. Think of it as the same experience as HMR (Hot Module Replacement) in web development.

Now let's build the Todo app in earnest.

5. Building the Todo App

Now we implement the Todo app in App.tsx. The screen composition and state management are almost the same as the React we know, so here we'll point out only the parts that differ from the web and the parts that are Expo-specific. You can find the full code on GitHub.

In React Native, you use dedicated components instead of web tags.

• View / Text: corresponds to <div> / <p>. All text must go inside a Text
• TextInput: an input field. It receives values via onChangeText, not onChange
• FlatList: list rendering. A virtualized list that only draws the items visible on screen
• TouchableOpacity: a touch area that acts as a button
• Styles are written not in a CSS file but as objects created with StyleSheet.create (properties are camelCase, and Flexbox is the default for layout)

The state and core logic (add/complete/delete) are ordinary React code.

type Todo = { id: string; text: string; done: boolean };

const [todos, setTodos] = useState<Todo[]>([]);
const [text, setText] = useState('');

const addTodo = () => {
  const trimmed = text.trim();
  if (!trimmed) return;
  setTodos((prev) => [
    { id: Date.now().toString(), text: trimmed, done: false },
    ...prev,
  ]);
  setText('');
};

const toggleTodo = (id: string) => {
  setTodos((prev) =>
    prev.map((t) => (t.id === id ? { ...t, done: !t.done } : t)),
  );
};

const deleteTodo = (id: string) => {
  setTodos((prev) => prev.filter((t) => t.id !== id));
};

The screen consists of an input field (TextInput + an add button) and a list (FlatList); tapping an item toggles completion, and pressing "Delete" removes it. Since the full JSX and styles (StyleSheet) are lengthy, refer to the GitHub source. At this point, you have a Todo app that works in memory.

The result after adding 4 todos and marking 2 of them complete (✅, strikethrough) — it works identically in the Web and the Expo Go app.

Persisting Data (AsyncStorage)

Right now, the app loses all its tasks when you close and reopen it. That's because all state lives only in memory. To save data on the device, we use AsyncStorage (an asynchronous key-value local storage).

Here is where Expo's real strength shows. When adding a native module, you use npx expo install instead of npm install.

npx expo install @react-native-async-storage/async-storage

expo install automatically picks and installs a version compatible with the current project's Expo SDK version. Native modules are sensitive to compatibility depending on the SDK version, and Expo takes care of matching this for you. On top of that, you don't need to touch native code directly or eject the project.

Now, with useEffect, we (1) load the saved list when the app starts and (2) save it whenever the list changes.

const STORAGE_KEY = '@expo_todo_app/todos';

const [loaded, setLoaded] = useState(false);

// Load saved todos when the app starts
useEffect(() => {
  (async () => {
    const raw = await AsyncStorage.getItem(STORAGE_KEY);
    if (raw) setTodos(JSON.parse(raw));
    setLoaded(true);
  })();
}, []);

// Save whenever todos change (after the initial load completes)
useEffect(() => {
  if (!loaded) return;
  AsyncStorage.setItem(STORAGE_KEY, JSON.stringify(todos));
}, [todos, loaded]);

The reason for the loaded flag is to prevent the save effect from running before the initial load finishes and overwriting the existing data with an empty array. Now, even after adding items, fully quitting the app, and reopening it, the list is preserved as is.

6. Expo's Limitations and Considerations

Expo makes getting started easy, but it isn't a silver bullet. There are some limitations worth knowing before applying it in real-world projects.

• In Expo Go, you can only use the native modules included in the SDK. Arbitrary third-party native libraries (e.g., a specific payment SDK or a Bluetooth library) won't work directly in the Expo Go app. In that case, you need to create a development build (a development app you build yourself). In other words, the convenience of "scan a QR with Expo Go and run instantly" only holds within the scope of pure JS and built-in modules
• Reflecting the latest native features can be slow. A new OS feature or a particular native SDK may take time to be included in the Expo SDK, or you may have to write a config plugin yourself
• Versions are tied to the Expo SDK. It's hard to freely bump the versions of React Native or some libraries, and you have to follow the Expo SDK upgrade cycle. The fact that expo install enforces compatible versions is a convenience and a constraint at the same time
• Build and deployment are ultimately the native domain. To publish to the stores, you need EAS Build (cloud build, with a free quota) or a local native build. Development may be easy, but at the deployment stage you face the reality of native builds
• App size and low-level control. Because the Expo runtime is included, the binary size can be somewhat larger, and there can be constraints for apps that require fine-grained native handling, such as high-performance graphics or special hardware control

For reference, the old concept of "eject" (detaching Expo to switch to a pure native project) has now been replaced by prebuild and development builds. It's now common to add the native code you need while keeping Expo, so the old worry that "if you start with Expo, you'll get stuck later" has largely been resolved.

In summary, Expo is enough for most typical apps, and the limitations above mainly apply when you need deep native customization.

7. Conclusion

To summarize the flow of getting started with a React Native app using Expo:

1. Create a project with create-expo-app
2. Run instantly on Expo Go or the simulator with expo start
3. Write the screen and logic in App.tsx (check immediately with Fast Refresh)
4. Compose the UI with RN components like View/Text/TextInput/FlatList
5. Easily add native modules (AsyncStorage) with expo install

The core appeal of Expo is being able to build a working app with React knowledge alone, without complex native configuration.

Good topics to explore as next steps are:

• Expo Router: compose multiple screens and tab navigation with file-based routing
• EAS Build: build the app in the cloud and publish it to the App Store/Play Store
• Make use of various Expo SDKs (camera, location, notifications, etc.)

8. References

• Expo Official Docs
• create-expo-app Docs
• AsyncStorage Docs
• Full Source Code (GitHub)

Back when I worked with Linux servers a lot, I couldn't imagine getting things done without tmux. Then I moved to mostly local development and forgot about it for a while, but lately, using terminal-based AI coding tools like Claude Code, I've started reaching for it again. So I figured I'd take this chance to lay out tmux from scratch, from a beginner's perspective.

If any of these sound familiar, tmux might be the answer.

• You have 10 terminal tabs open and have no idea what's where
• Your SSH connection dropped while working on a remote server, and the build or script that was running got wiped out entirely
• You want to see code editing and logs on one screen, but you keep switching back and forth between windows

This guide covers installation on macOS, walks through the concepts, basic usage, and a minimal config in order, and finishes by introducing how to use it alongside a Claude Code Session. You can just follow along from top to bottom.

2. What is tmux?

tmux is short for terminal mux(multiplexer), i.e. "terminal multiplexer." It's a tool that lets you handle multiple workspaces within a single terminal window and keep those workspaces running in the background.

There are two core values a beginner should remember.

① Session persistence — A tmux Session stays alive in the background even if you close the terminal window or your SSH connection drops. Later, all you have to do is attach again, and your work picks up as if it was never interrupted. The "SSH dropped and my build got wiped out" problem I mentioned earlier disappears right here.

② Screen splitting — You can divide a single screen into multiple Windows and Panes to view several tasks at once. You can keep an editor, logs, and a dev server all in view while you work.

To sum it up in one line, tmux is a workspace that doesn't disappear when you close it and that you can freely divide with partitions.

3. Installation (macOS)

On macOS, it's a one-liner with Homebrew.

brew install tmux

Once installation finishes, check the version.

tmux -V
# tmux 3.5a  (example)

If a version string is printed, you're ready to go. Now, type tmux in your terminal and your first Session begins.

4. Core Concepts: Session, Window, Pane

To use tmux, you need to know three units. They form a containment hierarchy in the order Session > Window > Pane.

• Session: The top-level workspace unit in tmux. Typically you use one Session per project or task. The detach/attach mentioned earlier targets exactly this Session
• Window: Think of it as a "tab" inside a Session. It takes up the whole screen, and you switch between multiple Windows
• Pane: A split screen within a Window. Multiple Panes are visible at once inside a single Window

To put it together, a single Session contains several Windows, and a single Window contains several Panes. By analogy with a browser, a Window is like a "tab," and a Pane is like a "split screen" that divides one tab left/right or top/bottom.

In practice, if you split one Window into three Panes, it looks like the image below. One Pane on top and two Panes on the bottom are all visible on one screen at once, and the bottom line is the status bar that shows the Window list and status.

5. Basic Usage

Almost every tmux shortcut works by pressing Ctrl+b first and then pressing the next key. This Ctrl+b is called the prefix key. For example, Ctrl+b c means "press Ctrl+b, release it, then press c." Just remember that you press them in sequence, not at the same time. (This prefix key can be changed to another key, which is covered in Section 6.)

5.1 Session

A Session is the unit that holds the entire workspace. Typically you create one Session per project, detach when you're done to step out, and attach again later to continue. The three you'll use most often are these.

• Start a new Session (with a name): tmux new -s my-project
• Step out of a Session (detach): Ctrl+b d (the Session stays alive)
• Attach to a Session again: tmux attach -t my-project

Even after you detach, the work inside the Session keeps running in the background. This detach/attach is the heart of tmux. The rest of the Session-related commands are as follows.

5.2 Window

A Window is a "tab" inside a Session. If you split Windows by the nature of the task (e.g. one for editing, one for the server), it's convenient to switch between them. The ones you'll use most are creating a new Window and moving between them.

• New Window: Ctrl+b c
• Next / previous Window: Ctrl+b n / Ctrl+b p
• Jump by number: Ctrl+b 0 ~ Ctrl+b 9

The rest of the Window-related shortcuts are as follows.

5.3 Pane

A Pane is a split screen that divides a Window left/right or top/bottom. You use it when you want to see code, logs, and server output at the same time on one screen. The ones you'll use most are splitting and moving.

• Split left/right: Ctrl+b %
• Split top/bottom: Ctrl+b "
• Move between Panes: Ctrl+b arrow key

The rest of the Pane-related shortcuts are as follows.

6. Minimal .tmux.conf Config

There's no need to deck it out lavishly from the start. Let's put just four things that make a big difference for beginners into ~/.tmux.conf.

# 1) Change prefix to Ctrl+a (if Ctrl+b doesn't feel right)
unbind C-b
set -g prefix C-a
bind C-a send-prefix

# 2) Enable mouse for Pane selection/resizing/scrolling
set -g mouse on

# 3) Make split shortcuts intuitive ( | left/right, - top/bottom )
bind | split-window -h
bind - split-window -v

# 4) Config reload shortcut (prefix r)
bind r source-file ~/.tmux.conf \; display "Reloaded!"

After saving, to apply it, press Ctrl+b r inside tmux. There's also the option of restarting with tmux kill-server, but be careful—this terminates every running Session. Usually the Ctrl+b r reload is enough.

For reference, changing the prefix to Ctrl+a in setting #1 is purely a matter of taste, an optional choice. Changing it makes it differ from the default prefix, which can be confusing. Just remember that all the shortcuts used in the rest of this article are based on the default prefix Ctrl+b.

7. Using It with Claude Code

That covers the tmux fundamentals. Now let's come back to what I mentioned at the start—the reason I started using tmux often again. Claude Code and tmux pair quite well. There are two reasons.

• Long autonomous work survives via detach. If you hand Claude Code a long task and step out with Ctrl+b d, the work keeps running even after you close the terminal
• You can work in parallel on one screen. Splitting Claude Code, the dev server, and logs into Panes and viewing them at once keeps your workflow from breaking

Creating and Naming a Session per Folder

When you move between several projects using Claude Code, it's convenient to keep one tmux Session running per project (folder). On top of that, if you use multiple machines (laptop, desktop, mini PC, etc.), Session names can collide, so naming them with the <machine>-<folder> rule keeps things from getting confusing no matter where you attach. For example, if you open the blog folder on your desktop (m4), the Session name becomes m4-blog.

Going one step further, it's nice to pass the same name along when you launch Claude Code in each Session. -n <name> gives the Claude session a name and shows it in the prompt, the resume picker, and the terminal title, while --remote-control <name> turns on remote control under that name. Even if you attach from your phone or another PC, "which task this is right now" is clear from the name alone.

Below is a simplified version of the script I use. You just need to change WORKSPACES (the folder list) and VALID_MACHINES (machine names) to match your own environment.

#!/usr/bin/env bash
set -euo pipefail

# ===== Config (edit to match your own environment) =====
WORKSPACES=(blog inspireme markora)   # Folder names under ~/src
VALID_MACHINES=(m1 m4 mini)           # Machine names (laptop/desktop, etc.)
SRC_DIR="${SRC_DIR:-$HOME/src}"
CLAUDE_CMD="${CLAUDE_CMD:-claude}"

# Session name rule: <machine>-<folder>  (replace . : in the folder with -)
session_name() { echo "$1-${2//[.:]/-}"; }

# Command to run in the Session: give Claude a name (-n) and a remote-control name (--remote-control)
launch_cmd() { echo "$CLAUDE_CMD -n $1 --remote-control $1"; }

create_one() { # <machine> <directory> <folder>
  local session; session="$(session_name "$1" "$3")"
  if tmux has-session -t "$session" 2>/dev/null; then
    echo "Already exists, skipping -> $session"
    return 0
  fi
  tmux new-session -d -s "$session" -c "$2" "$(launch_cmd "$session")"
  echo "Created -> $session ($2)"
}

# Usage: claude_tmux_sessions.sh <machine> [<folder>]
#   If the folder is omitted, all of WORKSPACES; if specified, just that one folder
machine="${1:?A machine name is required (e.g. m4)}"
folder="${2:-}"

if [[ -n "$folder" ]]; then
  create_one "$machine" "$SRC_DIR/$folder" "$folder"
else
  for f in "${WORKSPACES[@]}"; do
    [[ -d "$SRC_DIR/$f" ]] && create_one "$machine" "$SRC_DIR/$f" "$f"
  done
fi

echo "----- Current tmux sessions -----"
tmux ls
echo "Connect: tmux attach -t <session-name>"

Using it is simple.

• Launch all defined folders at once: claude_tmux_sessions.sh m4
• Launch just one specific folder: claude_tmux_sessions.sh m4 blog

Then Sessions like m4-blog and m4-inspireme are created per folder, and Claude Code is running under the same name inside each Session. From anywhere, you can attach with tmux attach -t m4-blog and continue working. If you leave it detached, the work keeps running even if you close your laptop or your SSH drops, so you can leave it running on a remote server and continue the same task while moving between home, the office, and your phone. (The actual script also includes a feature to clean up the Sessions you created all at once with --kill.)

Note: Appending --dangerously-skip-permissions to CLAUDE_CMD lets you skip the permission prompt every time, but since the tool then runs commands without confirmation, use it only in a trusted environment. Also, options like -n and --remote-control may differ depending on your Claude Code version, so check with claude --help.

Caution: If you open the same repo in multiple Sessions at once and Claude edits the same file simultaneously, conflicts can occur. For parallel work, it's safer to split by folder or separate them with git worktree.

8. Wrapping Up

The real value of tmux can be summed up in one line: a workspace that doesn't disappear when you close it. Screen splitting is handy too, but in the end the biggest change is escaping the state of "not being able to close the terminal for fear of losing my work."

You don't need to memorize every shortcut from the start. You can start by getting these five into your hands.

• New Session: tmux new -s name
• Step out: Ctrl+b d
• Re-attach: tmux attach -t name
• New Window: Ctrl+b c
• Split left/right: Ctrl+b %

In particular, I recommend getting comfortable with Ctrl+b d (detach) and tmux attach (re-attach) first. Once just these two are in your hands, the way you approach the terminal changes. After that, layer it on top of long-running work like Claude Code, and you'll quickly feel why you find yourself reaching for tmux again.

9. References

• tmux + Claude Code: The Perfect Terminal Workflow
• Using tmux with Claude Code
• How to Run Claude Code with tmux on a VPS
• Seamless Claude Code Handoff: SSH From Your Phone With tmux
• Claude Code Multi-Agent tmux Setup

As a Go application grows, assembling dependencies becomes complex. You have to call constructors one by one in main(), line up parameter orders, and manage the lifecycle yourself. uber/fx is a DI (Dependency Injection) framework for Go that solves this problem.

The scope of this article is as follows.

• Basic API: fx.Provide, fx.Invoke, fx.Supply, fx.New
• Lifecycle management: fx.Lifecycle (OnStart/OnStop)
• Grouping and extension patterns: fx.Module, fx.Decorate
• Multiple instances of the same type: fx.Annotate + name: / group: tags (fx.Group)
• Module encapsulation: fx.Private
• Testing strategies: fxtest.New, fx.Replace, fx.Populate

2. fx Basics

2.1 Why DI Is Needed in Go

A real-world project with separated layers has many dependencies. For example, to construct an Article API, you must assemble the following dependencies in order.

// Manual DI: assembled directly in main()
cfg, _ := config.New()
db, _ := database.New(cfg)

authorRepo := author.NewMysqlAuthorRepository(db)
articleRepo := article.NewMysqlArticleRepository(db)

timeout := time.Duration(cfg.Context.Timeout) * time.Second
articleUsecase := article.NewArticleUsecase(articleRepo, authorRepo, timeout)

e := NewEcho()
article.NewArticleHandler(e, articleUsecase)

e.Start(cfg.Server.Address)

As the number of dependencies grows, this code becomes dramatically more complex. Get the order wrong and you get a compile error, and every time you add a new service you have to modify main().

uber/fx solves this problem. It analyzes the parameters and return types of constructor functions to build the dependency graph automatically, and creates everything in the correct order.

go get go.uber.org/fx

2.2 fx Basic Concepts

Before diving in, here is an at-a-glance summary of the fx methods covered in this article. fx has many methods that are easy to confuse, so use the table below as a map while reading. The order of categories matches the article's flow (basics → extension → testing).

The following sections cover each method one by one with hands-on examples. First, let's look at the most basic building blocks: fx.Provide, fx.Invoke, fx.Supply, and fx.New.

A constructor registered with fx.Provide() is not executed immediately. It is created lazily when the corresponding type is needed elsewhere.

// fx_test.go
func TestFx_Provide_Invoke(t *testing.T) {
    var svc *UserService

    app := fxtest.New(t,
        // fx.Provide: only registers the constructor. It is not run immediately; it is called lazily when needed as a dependency.
        fx.Provide(
            NewLogger,       // returns the Logger interface
            NewMysqlUserRepo, // returns the UserRepository interface (needs Logger)
            NewUserService,   // returns *UserService (needs UserRepository)
        ),
        // fx.Invoke: a side effect run immediately at app startup. Here it pulls the assembled UserService into an external variable.
        fx.Invoke(func(s *UserService) {
            svc = s
        }),
    )
    defer app.RequireStop()
    app.RequireStart()

    assert.Equal(t, "user-1", svc.repo.FindByID(1))
}

fx.Supply() provides an already-built value directly, without a constructor.

// fx_test.go
type Config struct {
    DBHost string
    DBPort int
}

cfg := &Config{DBHost: "localhost", DBPort: 3306}

app := fxtest.New(t,
    fx.Supply(cfg), // register the value directly without a constructor
    fx.Invoke(func(c *Config) {
        // c.DBHost == "localhost"
    }),
)

2.3 Applying fx to a Real Project

Converting the manual DI code to fx looks like this.

// cmd/main.go
app := fx.New(
    fx.Provide(
        config.New,              // *config.Config
        database.New,            // *sql.DB (needs *config.Config)
        NewEcho,                 // *echo.Echo
        ProvideBasicConfig,      // time.Duration

        article.NewArticleHandler,         // Handler (needs Echo, UseCase)
        article.NewArticleUsecase,         // UseCase (needs Repo, AuthorRepo, Duration)
        article.NewMysqlArticleRepository, // Repository (needs DB)

        author.NewMysqlAuthorRepository,   // AuthorRepo (needs DB)
    ),
    fx.Invoke(registerHooks),  // start the server
)

fx looks at each constructor's parameter types to determine the dependency order automatically. For example, database.New(cfg *config.Config) needs a *config.Config, so config.New() is called first.

Looking at each constructor's signature, the dependency relationships are clear.

// pkg/config/config.go
func New() (*config.Config, error) { ... }

// pkg/database/db.go
func New(cfg *config.Config) (*sql.DB, error) { ... }

// article/usecase.go
func NewArticleUsecase(
    a domain.ArticleRepository,
    ar domain.AuthorRepository,
    timeout time.Duration,
) domain.ArticleUsecase { ... }

// article/handler.go
func NewArticleHandler(e *echo.Echo, us domain.ArticleUsecase) *ArticleHandler { ... }

fx.Provide() accepts not only predefined constructors like the ones above but also anonymous functions directly. For simple conversion logic, it's convenient to handle it inline rather than creating a separate constructor file. Expanding the ProvideBasicConfig above into an anonymous function looks like this.

// cmd/main.go
app := fx.New(
    fx.Provide(
        config.New,
        database.New,
        NewEcho,

        // an anonymous function can be registered as a constructor too — only the parameters and return type need to match
        func(cfg *config.Config) time.Duration {
            return time.Duration(cfg.Context.Timeout) * time.Second
        },

        article.NewArticleHandler,
        article.NewArticleUsecase,
        article.NewMysqlArticleRepository,
        author.NewMysqlAuthorRepository,
    ),
    fx.Invoke(registerHooks),
)

Just like a named constructor, fx analyzes the anonymous function's parameters (*config.Config) and return type (time.Duration) and wires it into the dependency graph. Only the form of the function differs; from fx's perspective it's the same constructor.

Visualizing the dependency graph that fx builds from the constructors registered this way looks like this.

graph TD
    Config["config.New()"] --> Database["database.New()"]
    Database --> ArticleRepo["NewMysqlArticleRepository()"]
    Database --> AuthorRepo["NewMysqlAuthorRepository()"]
    ArticleRepo --> ArticleUsecase["NewArticleUsecase()"]
    AuthorRepo --> ArticleUsecase
    ArticleUsecase --> ArticleHandler["NewArticleHandler()"]
    Config --> Echo["NewEcho()"]
    Config --> RegisterHooks["registerHooks()"]
    Echo --> RegisterHooks
    ArticleHandler --> RegisterHooks

fx builds this graph automatically using only the constructors' parameters and return types. If there is a circular dependency, it prints a clear error message at app startup.

2.4 Lifecycle Management

fx.Lifecycle manages app startup and shutdown. You start the server in OnStart and handle graceful shutdown in OnStop.

// cmd/main.go
func registerHooks(lifecycle fx.Lifecycle, e *echo.Echo, cfg *config.Config) {
    lifecycle.Append(
        fx.Hook{
            OnStart: func(context.Context) error {
                fmt.Println("Starting server")
                go e.Start(cfg.Server.Address)
                return nil
            },
            OnStop: func(context.Context) error {
                fmt.Println("Stopping server")
                return nil
            },
        },
    )
}

registerHooks is registered with fx.Invoke(). One thing to watch out for is the timing of execution. fx.Invoke (and fx.Populate, which uses it internally) runs immediately at the time fx.New() is called, not at app.Start(). So the registerHooks above is called during the fx.New() step and only registers the OnStart/OnStop hooks on the Lifecycle; the actual server boot (the body of OnStart) is triggered later at app.Start(ctx). This is why fx.Lifecycle has this two-phase structure — register the hooks early via Invoke, and defer running the hook bodies until Start.

// fx_test.go
func TestFx_Lifecycle(t *testing.T) {
    var startCalled, stopCalled bool

    app := fxtest.New(t,
        fx.Invoke(func(lc fx.Lifecycle) {
            lc.Append(fx.Hook{
                OnStart: func(context.Context) error {
                    startCalled = true
                    return nil
                },
                OnStop: func(context.Context) error {
                    stopCalled = true
                    return nil
                },
            })
        }),
    )

    app.RequireStart()
    assert.True(t, startCalled)

    app.RequireStop()
    assert.True(t, stopCalled)
}

3. Extension Patterns

From fx.Module to fx.Private, let's look at the extension tools that build on top of the fx basics.

3.1 The fx.Module Pattern

fx.Module() groups related dependencies by domain. As the app grows, listing all constructors together in fx.Provide() hurts readability. Splitting them into Modules makes concerns clearer.

// fx_test.go
var UserModule = fx.Module("user",
    fx.Provide(
        NewMysqlUserRepo,
        NewUserService,
    ),
)

var OrderModule = fx.Module("order",
    fx.Provide(
        NewMysqlOrderRepo,
        NewOrderService,
    ),
)

app := fxtest.New(t,
    fx.Provide(NewLogger), // shared dependency
    UserModule,
    OrderModule,
    fx.Invoke(func(u *UserService, o *OrderService) {
        // all dependencies are wired automatically
    }),
)

In real projects, a common pattern is to define a Module variable in each domain package and compose them in main().

// real-world application example
app := fx.New(
    fx.Provide(config.New, database.New, NewEcho),
    article.Module,   // article domain module
    author.Module,    // author domain module
    payment.Module,   // payment domain module
    fx.Invoke(registerHooks),
)

fx.Module is available from v1.17.0+. In earlier versions, you can do similar grouping with fx.Options(), but it does not support module names or scope isolation.

3.2 The fx.Decorate Pattern

fx.Decorate() wraps an existing dependency to add behavior. It's the same concept as the decorator pattern, used for logging, caching, metrics collection, and so on.

// fx_test.go
// logging decorator: wraps the existing UserRepository
type loggingUserRepo struct {
    inner  UserRepository
    logger Logger
    calls  []string
}

func (r *loggingUserRepo) FindByID(id int) string {
    r.calls = append(r.calls, fmt.Sprintf("FindByID(%d)", id))
    return r.inner.FindByID(id) // call the original
}

app := fxtest.New(t,
    fx.Provide(NewLogger, NewMysqlUserRepo, NewUserService),
    // replace the existing UserRepository with a logging wrapper
    fx.Decorate(func(repo UserRepository, logger Logger) UserRepository {
        return &loggingUserRepo{inner: repo, logger: logger}
    }),
    fx.Invoke(func(svc *UserService) {
        svc.repo.FindByID(1) // called through the logging wrapper
    }),
)

fx.Decorate() takes the original dependency as a parameter and returns a new wrapped instance. UserService receives the wrapped Repository automatically, with no changes.

fx.Decorate is available from v1.18.0+.

3.3 fx.Annotate + Named Dependencies

When you need to distinguish multiple instances of the same type, use fx.Annotate() and the name tag. A typical case is separating Read/Write DBs.

// fx_test.go
type DBConnection struct {
    Name string
    DSN  string
}

func NewReadDB() *DBConnection {
    return &DBConnection{Name: "read", DSN: "read-replica:3306"}
}

func NewWriteDB() *DBConnection {
    return &DBConnection{Name: "write", DSN: "primary:3306"}
}

Use fx.Annotate() to give each constructor a name.

// fx_test.go
fx.Provide(
    fx.Annotate(NewReadDB, fx.ResultTags(`name:"readDB"`)),
    fx.Annotate(NewWriteDB, fx.ResultTags(`name:"writeDB"`)),
    NewDBService,
)

On the receiving side, match by name tag in an fx.In struct.

// fx_test.go
type DBParams struct {
    fx.In
    ReadDB  *DBConnection `name:"readDB"`
    WriteDB *DBConnection `name:"writeDB"`
}

func NewDBService(params DBParams) *DBService {
    return &DBService{
        readDB:  params.ReadDB,  // read-replica:3306
        writeDB: params.WriteDB, // primary:3306
    }
}

3.4 Collecting Multiple Implementations of the Same Interface with fx.Group

The name: tag is for identifying the same type individually. But if you want to inject multiple implementations of the same interface all at once — for example, sending a notification to every Notifier — name: is not enough, because you'd have to give each implementation a different name and receive them one by one on the receiving side.

The group: tag solves this problem. Implementations registered in the same group are injected together as a slice.

// fx_test.go
type Notifier interface {
    Send(msg string) string
}

type EmailNotifier struct{}
func (e *EmailNotifier) Send(msg string) string { return "email:" + msg }

type SlackNotifier struct{}
func (s *SlackNotifier) Send(msg string) string { return "slack:" + msg }

type SMSNotifier struct{}
func (s *SMSNotifier) Send(msg string) string { return "sms:" + msg }

Use fx.Annotate() and fx.ResultTags() to register each constructor in the same group.

// fx_test.go
fx.Provide(
    fx.Annotate(func() Notifier { return &EmailNotifier{} },
        fx.ResultTags(`group:"notifiers"`)),
    fx.Annotate(func() Notifier { return &SlackNotifier{} },
        fx.ResultTags(`group:"notifiers"`)),
    fx.Annotate(func() Notifier { return &SMSNotifier{} },
        fx.ResultTags(`group:"notifiers"`)),
    NewNotifierService,
)

The receiving side takes it as a slice field with a group: tag in an fx.In struct.

// fx_test.go
type NotifierParams struct {
    fx.In
    Notifiers []Notifier `group:"notifiers"`
}

type NotifierService struct {
    notifiers []Notifier
}

func NewNotifierService(p NotifierParams) *NotifierService {
    return &NotifierService{notifiers: p.Notifiers}
}

A representative real-world use is collecting multiple external service clients into a single interface slice. Even when a new implementation is added, the receiving-side code does not change.

To summarize the difference between name: and group::

3.5 Encapsulating a Module with fx.Private

Even if you split domains with fx.Module(), every fx.Provide() is exposed globally by default. For a dependency you want to use only inside a Module, you can block exposure with fx.Private. It's useful for preventing another Module from accidentally sharing the same instance of an infrastructure dependency such as a database handle or external API client.

When you place fx.Private inside the same fx.Provide() call alongside other constructors, it makes that entire group Module-private.

// fx_test.go
type internalDB struct {
    name string
}

func newInternalDB() *internalDB {
    return &internalDB{name: "private-db"}
}

type ModuleService struct {
    db *internalDB
}

func newModuleService(db *internalDB) *ModuleService {
    return &ModuleService{db: db}
}

PrivateModule := fx.Module("private",
    fx.Provide(
        newInternalDB,
        fx.Private,        // makes the entire fx.Provide() group Module-internal
    ),
    fx.Provide(newModuleService), // ModuleService is exposed externally
)

*internalDB can only be injected into newModuleService inside PrivateModule. If you request *internalDB directly from outside the Module, fx returns an error when constructing the dependency graph (fx.Populate is covered in §2.8.3).

// fx_test.go
// attempting to extract *internalDB directly from outside → fx.New returns an error
var leaked *internalDB
leakApp := fx.New(
    PrivateModule,
    fx.Populate(&leaked),
    fx.NopLogger,
)
// leakApp.Err() != nil

fx.Private is available from v1.20.0+. In earlier versions, even with fx.Module isolation, all Provides are registered in the global graph.

4. Testing Strategies

An app built with fx is tested with the fxtest package. We'll also look at mock injection and instance extraction.

4.1 fxtest.New

fxtest.New() creates a test-only app. It cleans up automatically on test failure, and fx logs are included in the test output.

// fx_test.go
app := fxtest.New(t,
    fx.Provide(NewLogger, NewMysqlUserRepo, NewUserService),
    fx.Invoke(func(svc *UserService) { ... }),
)
defer app.RequireStop()
app.RequireStart()

4.2 Injecting a Mock with fx.Replace

fx.Replace() completely replaces an existing Provide. It's useful for injecting a Mock instead of the real implementation in a test.

// fx_test.go
type mockUserRepo struct{}

func (r *mockUserRepo) FindByID(id int) string {
    return fmt.Sprintf("mock-user-%d", id) // Mock response
}

app := fxtest.New(t,
    fx.Provide(NewLogger, NewMysqlUserRepo, NewUserService),
    // replace the real UserRepository with a Mock
    fx.Replace(fx.Annotate(&mockUserRepo{}, fx.As(new(UserRepository)))),
    fx.Invoke(func(svc *UserService) {
        result := svc.repo.FindByID(1)
        // result == "mock-user-1"
    }),
)

fx.As(new(UserRepository)) registers *mockUserRepo after type-converting it to the UserRepository interface.

4.3 Extracting an Instance with fx.Populate

So far we've captured instances into external variables in the fx.Invoke(func(s *Svc) { svc = s }) form. fx.Populate does the same thing more concisely.

In fact, fx.Populate is a convenience function implemented internally with fx.Invoke. fx.Populate(&svc) is equivalent to automatically generating "an fx.Invoke that assigns the injected value to svc." In other words, the two are essentially the same. The difference is in purpose. fx.Invoke exists to do something with the pulled-out dependency, so you can call, verify, or do anything in the closure body (extraction is just one of those things); fx.Populate exists for extraction itself, so it omits the closure when it would just be boilerplate.

Comparing the two methods:

// fx_test.go
// Approach 1: capture via an fx.Invoke closure (the approach used earlier)
var svc1 *UserService
app1 := fxtest.New(t,
    fx.Provide(NewLogger, NewMysqlUserRepo, NewUserService),
    fx.Invoke(func(s *UserService) {
        svc1 = s
    }),
)

// Approach 2: extract directly with fx.Populate
var svc2 *UserService
app2 := fxtest.New(t,
    fx.Provide(NewLogger, NewMysqlUserRepo, NewUserService),
    fx.Populate(&svc2),
)

The difference is even more pronounced when extracting multiple instances at once.

// fx_test.go
var (
    svc    *UserService
    logger Logger
)
app := fxtest.New(t,
    fx.Provide(NewLogger, NewMysqlUserRepo, NewUserService),
    fx.Populate(&svc, &logger),
)

The selection guide is simple.

5. Wrapping Up

fx has many methods and is easy to confuse. Here's a summary of what to choose in each situation.

Remember just one thing. You don't need to manage every dependency with fx. Simple value objects and utilities are clearer to create directly, and fx shines most when you focus it on components that need lifecycle management (DB connections, HTTP servers, external clients). Because it's reflection-based, you give up some compile-time type safety, but its detailed runtime error messages and real-world productivity more than make up for it.

The full source is available in the following two places.

• Per-method learning examples (the // fx_test.go code in this article): golang/third-party/fx
• Real-world application example (Clean Architecture + fx, the // cmd/main.go code): project-layout/go-clean-arch-v2

6. References

• uber/fx Official Docs
• uber/fx GitHub
• uber/dig GitHub
• fx.Module introduced (v1.17)
• fx.Decorate introduced (v1.18)
• Go Dependency Injection - uber/fx
• Value Groups (fx Docs)
• fx.Private introduced (v1.20)
• fx.Populate API

When you write code with Claude Code, there's one recurring frustration. You start out clean, but at some point the context becomes scattered, you lose track of how far you've gotten, and it becomes ambiguous where the tests should stop and restart. Give the AI autonomy and it gets improvisational; try to control it and a human has to step in at every turn.

Superpowers is a plugin that structures this flow. It organizes ideas into a spec with brainstorm, decomposes them into work-unit plans with writing-plans, goes through per-phase implementation + automatic review with subagent-driven-development, runs a final check with requesting-code-review, and handles PR/cleanup with finishing-a-development-branch—these five stages are bundled into one complete workflow.

In this article, I'll lay out the core superpowers skills all at once, then walk step by step through an actual case where I built an Echo + React Todo web app from scratch all the way to PR/merge. At the end, I've added a separate honest-review section based on actually using it, so colleagues considering adoption can weigh cost vs. value.

This article assumes a reader who is reasonably familiar with Claude Code itself and the Skill/Plugin concepts. If any concept is new to you, it helps to first read Complete Guide to Claude Code Extensions: Command, Skill, Subagent and Complete Guide to Claude Code Plugin Hooks.

2. What Is Superpowers

Superpowers is a plugin officially registered in the Claude Code plugin marketplace run by Anthropic. Unlike an ordinary plugin that provides a single function, its distinguishing feature is that it provides a bundle of multiple skills + a workflow in which the skills are invoked in a defined order.

Where the existing Skill guide explains "what each skill is and when it's invoked," this article steps up one level to cover in what order multiple skills are woven together to form a single cycle.

3. Core Skill Catalog

There are many skills inside Superpowers, but the core ones that form the full cycle are eight. Let's first skim them all at once, then look at each skill one paragraph at a time.

3.1 brainstorming

A skill invoked with /superpowers:brainstorming. It takes an idea expressed in natural language and asks the user one multiple-choice question at a time, organizing it into spec.md. It saves the decisions to docs/superpowers/specs/YYYY-MM-DD-<topic>-design.md and commits them.

The key is "one question at a time." Rather than dumping the stack, feature scope, libraries, and tone all at once, it proceeds like a decision tree. For visual decisions like UI design, it can also bring up a visual companion (browser mockup comparison).

3.2 writing-plans

Once the spec is complete, superpowers:writing-plans is invoked automatically. It decomposes the spec into per-phase tasks and explicitly writes the following five steps for each task.

1. Write a failing test
2. Confirm the test fails (Red)
3. Minimal implementation
4. Confirm the test passes (Green)
5. Commit

Each task is one commit unit, usually 2-5 minutes of work. The plan is saved to docs/superpowers/plans/YYYY-MM-DD-<topic>-plan.md.

3.3 subagent-driven-development

Once the plan is ready, two execution options are presented. subagent-driven dispatches a new subagent for each task to isolate context. A single task goes through the following flow.

1. Implementer subagent — receives the task instructions, writes code, tests, self-reviews, and commits
2. Spec compliance reviewer subagent — verifies the implementation matches the spec exactly
3. Code quality reviewer subagent — checks code quality, test gaps, and pitfalls

All three stages must pass before moving to the next task. If a review finds an issue, the implementer is called again to fix → re-review. With no context contamination, one subagent is responsible for one task.

3.4 executing-plans (alternative)

An alternative that runs the same plan inline within the same session. At each step it directly updates the checkbox in the plan file to - [x] as it proceeds. There's no subagent dispatch cost, but also no context isolation, so on large work context contamination can accumulate.

Selection criteria:

• subagent-driven: large multi-stage work, many tasks, where the value of the review cycle is high
• executing-plans: short and simple work, where the plan file itself serves as progress tracking

3.5 requesting-code-review

Before the entire cycle ends, you get one more comprehensive review. It bundles all commits in the branch and checks spec compliance, regressions, pitfalls, and items needing additional tests. Comments classified as critical/important/minor come back.

3.6 test-driven-development

TDD is already built into the task skeleton of writing-plans, so a separate invocation is rare. But it guides the implementer subagent to consciously follow the TDD cycle. The key is confirming, in the Red stage, that the test really fails.

3.7 using-git-worktrees

Before starting large work, it creates an isolated worktree so the current working directory isn't affected. It's often omitted for a single learning cycle, but it's recommended in real-world environments where you work on multiple features simultaneously.

3.8 finishing-a-development-branch

Invoked at the very end after all tasks are done. It presents the following as structured options.

• choose among merge / PR / keep a separate branch
• automatic push policy
• branch cleanup

In this article's case, I didn't invoke this skill explicitly; following the user's global policy (no arbitrary push) I ran gh pr create + gh pr merge directly—I'll revisit this in the review section.

4. The Full Cycle Flow

It becomes clear when you see, in a diagram, the order in which the core skills are woven together.

flowchart LR
    A[brainstorming] --> B[writing-plans]
    B --> C[subagent-driven-development]
    C --> D[requesting-code-review]
    D --> E[finishing-a-development-branch]

Each arrow means an automatic invocation. When brainstorming finishes writing the spec, after user approval it automatically calls writing-plans, and once the plan is written the user chooses the execution mode (subagent-driven or executing-plans). At the end, finishing-a-development-branch presents the PR/merge options.

4.1 Points of User Intervention

Across the entire flow, the points where the user must decide are as follows.

Outside these six points, it's almost all automatic. Because the points requiring human time are clear, the workflow's predictability is high.

4.2 Tracking Method (subagent-driven vs executing-plans)

Progress tracking happens in one of two places.

• subagent-driven: an in-memory task list via TaskCreate/TaskUpdate. The - [ ] checkboxes in the plan file are not updated.
• executing-plans: marking directly by editing the plan file to - [x]. The plan file itself is the progress tracker.

The result is the same, but the artifacts differ. Because this article's case used subagent-driven, the plan file remained - [ ] to the end—I'll revisit this in the review section.

4.3 Directory Structure

The work output is organized into the following form.

project/
├── docs/superpowers/
│   ├── specs/YYYY-MM-DD-<topic>-design.md   # brainstorming output
│   └── plans/YYYY-MM-DD-<topic>-plan.md     # writing-plans output
├── (actual code)
└── (tests)

The specs/plans are included together in the PR and become a permanent reference. Since the intent and steps of the work are recorded next to the code, even when you look back six months later it's easy to trace "why did I do it this way."

5. Case Study: A Todo Web App from Scratch to PR (Echo + React)

This section is the core of this guide. It walks step by step through the actual flow of building a learning Todo web app from brainstorm to PR/merge under ai/superpowers/todo/ in the tutorials-go repository. The resulting PR is #701.

Laying out the whole flow in advance:

flowchart LR
    S0["brainstorm start"] --> S1["write spec"]
    S1 --> S2["decompose plan into 11 phases"]
    S2 --> S3["implement Phase 0-10"]
    S3 --> S4["MCP playwright e2e"]
    S4 --> S5["PR / merge"]

Let's look at what command started each stage and what artifacts it left behind.

5.1 Brainstorming — Up to Writing the Spec

It starts with a single line, /superpowers:brainstorming. You pass a natural-language idea as the argument.

/superpowers:brainstorming I want to write sample code for a todo web application.
- stack: react, golang 1.25, inmemory
- I want to write the sample code here: /Users/user/src/workspace_blog3/tutorials-go/ai/superpowers
Note: the main purpose is to learn how to use superpowers

The skill immediately checks the context (go.mod, sibling directories, existing conventions), then presents multiple choices one question at a time. An excerpt of the actual questions received:

Each question shows a recommendation (one of A/B/C) along with an explanation of the trade-offs. After passing the 7 questions, a 9-section spec.md (2026-04-30-todo-app-design.md, 600+ lines) is generated automatically, ambiguities are reinforced inline via self-review, and then a user review gate opens.

Once approved, the next skill is invoked automatically.

5.2 Writing-plans — Decomposing the Plan into 11 Phases

superpowers:writing-plans reads the spec and creates a task-unit plan. In the Todo case, it was decomposed into the following 11 stages.

Each phase is one commit unit, averaging 5-10 minutes of work. The plan ran about 3500 lines, specifying the code/commands/expected output of every step.

5.3 Subagent-driven-development — 25 commits, two-stage review

This is the heart of the cycle. The following flow repeats for every phase.

flowchart LR
    P["task start"] --> I["implementer subagent"]
    I --> S["spec compliance reviewer"]
    S --> Q["code quality reviewer"]
    Q --> N["next task"]

All three subagents operate on the same task in independent contexts. In the actual case, there were two instances where this structure caught a critical issue.

Case ① — Phase 1 Korean length validation (caught by the TDD reviewer)

In the domain model's NewTodo.Validate(), the title length was being checked with len(), and the code quality reviewer pointed out the following.

todo.go:60 — Title length uses len() (bytes), not runes. A 100-character Korean title is 300 bytes, so it gets rejected. In this project where Korean content is a first-class concern, this is a bug.

I called the implementer again to add utf8.RuneCountInString + Korean boundary tests (200 chars valid / 201 chars invalid).

Case ② — Phase 10 DueDate pointer aliasing (caught by the final reviewer)

In the final review of the entire branch, the following was found.

store.go:39, 82 — Add/Update store the caller's *time.Time pointer as-is. The package GoDoc promises "callers cannot mutate stored state through returned references," but this promise is broken.

I added a defensive copy (a copyTimePointer helper) and included regression tests (TestStore_Add_DueDateNotAliased, TestStore_Update_DueDateNotAliased) along with it.

An excerpt of the representative commit flow:

A total of 25 commits piled up on the feat/todo-app branch.

5.4 Creating and Merging the PR

Branch push + PR creation + merge are each one line of command.

# push
git push -u origin feat/todo-app

# create PR (HEREDOC per CLAUDE.md policy)
gh pr create --title "feat: superpowers todo app (learning sample)" \
  --body "$(cat <<'EOF'
## Summary
- Echo + React + in-memory Todo web application (for learning)
- fully experienced the superpowers plugin skill cycle
... (omitted)
EOF
)" --assignee kenshin579

# merge
gh pr merge 701 --merge --delete-branch

Result: PR #701 merged, integrated into master. From the start of work to merge, it finished within a single session.

6. Getting Started

The procedure needed to adopt superpowers for the first time is short.

6.1 Installing the Plugin

Install it via the marketplace in Claude Code.

/plugin install superpowers@anthropic

(Check the exact command on the Anthropic Plugin Marketplace page. The channel/name may differ depending on the point in time.)

After installation, you're good if you see slash commands starting with /superpowers: in a new session.

6.2 Starting the First Cycle

/superpowers:brainstorming <a line or two of the idea in natural language>

After that, just follow this flow as-is.

1. Answer 7-10 multiple-choice questions
2. Review the auto-generated spec.md (you can request 1-2 rounds of changes)
3. Run the automatically invoked writing-plans
4. Review the generated plan.md
5. Choose the execution mode (subagent-driven recommended)
6. Implementation proceeds automatically (occasionally enter additional context when it gets stuck)
7. Apply the final review comments
8. Create the PR (after user approval)

6.3 Recommended Preparation

• Spell out the CLAUDE.md policy: if you write your push/PR automation policy in CLAUDE.md, the skill respects it (e.g., "DO NOT push without explicit consent").
• Code convention rules: if you write code-style/test conventions in .claude/rules/*.md, the reviewer subagent checks against them (e.g., gofmt, testify/assert, GoDoc, etc.).

6.4 Directory Structure (recap)

project/
├── docs/superpowers/
│   ├── specs/   # brainstorming output
│   └── plans/   # writing-plans output
├── code/
└── tests/

Commit the specs/plans together with the PR to leave them as a permanent reference. When you look back six months later, the answer to "why did I structure it this way" is right there.

7. What I Felt After Actually Trying It (honest review)

That's it for the guide-style information. This section is "observations from someone who actually ran one cycle." Please bear with a slightly informal tone.

What I Liked

• The entire development flow connects naturally: previously, I had to manually write a PRD → implementation plan → todo.md separately and review markdown at each stage, which took quite a bit of time. Superpowers ties brainstorm → spec → plan → implementation → review into one flow, so each stage's output naturally becomes the input to the next, and the documentation and review cost the worker spends drops significantly
• Almost zero context contamination: when a task ends, the context is cleaned up along with the implementer subagent → the reason I could finish a large PR (25 commits) in one session
• The two-stage spec/quality review pulls PR review cost inside the cycle: critical issues that pass compilation/tests (Korean rune count, DueDate aliasing) and a regression gap (a Vitest e2e config bug) were all discovered and fixed mid-cycle

Costs and Trade-offs

• Token usage ramps up fast: each task accumulates 3 dispatches—implementer + spec/quality reviewer—so consumption is heavy. Even on the Claude Max 100x plan, I experienced hitting a rate limit mid-cycle
• Plan file checkboxes are not auto-updated: subagent-driven tracks via an in-memory task list, and plan.md stays - [ ] to the end. If you want to use the plan as a permanent tracker, executing-plans is a better fit

Recommended Application Scenarios

In short: most powerful for multi-stage + multi-area work; for a single-file edit, a regular slash command is faster.

8. Conclusion

Run one cycle of Superpowers and one thing becomes clear. The efficiency of AI coding is influenced more by workflow structure than by the quality of individual prompts. With the same model and the same code-writing ability, forcing the flow of brainstorm → plan → impl → review → finish substantially raises the consistency and regression stability of the output.

Three lines of key takeaways:

1. It's powerful for multi-stage work. The scenario of building Domain + API + UI all at once is the sweet spot. For a one-line fix, it's overkill.
2. The two-stage review catches issues that were invisible. Even when compilation/tests pass, the promise between spec and code can be broken, and the reviewer verifies that.
3. It's very good as learning/onboarding material. The cycle itself remains in spec/plan in a reproducible form.

Things worth trying next:

• isolate multiple work with using-git-worktrees
• inline execution with executing-plans (auto-updating plan checkboxes)
• formally invoke the finishing-a-development-branch skill to be presented with PR/cleanup options

These three are the parts missing from this case, so I'll cover them separately in a follow-up article, or I'd love to hear the experiences of those who have tried them directly.

9. References

• Anthropic Claude Code official docs
• Claude Code Plugin Marketplace guide
• This case's PRs: tutorials-go #701 (full Todo implementation), #702 (FE theme redesign)
• Complete Guide to Claude Code Extensions: Command, Skill, Subagent
• Complete Guide to Claude Code Plugin Hooks
• Claude Code MCP Recommendation Guide

1. Introduction - Why the context Package Is Needed

When a server handles an HTTP request, it's common for a single request to be distributed across multiple goroutines. Three core requirements arise here.

• goroutine cancellation: when the client disconnects, all related goroutines must be cleaned up
• timeout management: you need to put a time limit on external API calls or DB queries
• passing request-scoped values: request ID, authentication info, etc. need to be passed along the function chain

The context package unifies these three into a single interface.

type Context interface {
    Deadline() (deadline time.Time, ok bool)
    Done() <-chan struct{}
    Err() error
    Value(key any) any
}

• Done(): returns a channel that closes when the context is canceled or expires
• Err(): returns the reason the Done channel closed (Canceled or DeadlineExceeded)
• Deadline(): returns the expiration time
• Value(): looks up a value stored in the context

2. context.Background() and context.TODO()

There are two empty contexts that serve as the root of every context tree.

ctx := context.Background() // the general root context
ctx := context.TODO()       // when you don't yet know which context to use

• context.Background(): used as the top-level context in the main function, initialization code, and tests
• context.TODO(): used temporarily when you haven't yet decided which context to pass. When you see a TODO in code review, it's a signal that "the context design here needs to be checked"

In practice, you mostly use context.Background() as the root and wrap it with WithCancel, WithTimeout, WithValue, etc. to create derived contexts.

3. WithCancel - Cancellation Propagation

3.1 Basic Usage

context.WithCancel returns a new context and a cancel function from a parent context. Calling cancel() closes the Done() channel and terminates the goroutine watching it.

func TestWithCancel(t *testing.T) {
    ctx, cancel := context.WithCancel(context.Background())

    var stopped atomic.Bool

    go func() {
        <-ctx.Done() // wait until cancel() is called
        stopped.Store(true)
    }()

    cancel() // cancel explicitly
    time.Sleep(50 * time.Millisecond)

    assert.True(t, stopped.Load())
    assert.ErrorIs(t, ctx.Err(), context.Canceled)
}

When cancel() is called, ctx.Done() closes and the goroutine wakes up. ctx.Err() returns context.Canceled.

If you're curious about the internal implementation of the cancel() function, see FAQ - cancel() internal implementation.

3.2 Cancellation Chain (parent -> child)

A context forms a tree structure. When a parent is canceled, all children are automatically canceled. Conversely, canceling a child does not affect the parent.

func TestCancelChain(t *testing.T) {
    parent, parentCancel := context.WithCancel(context.Background())
    child, childCancel := context.WithCancel(parent)
    defer childCancel()

    parentCancel() // cancel parent → child is canceled too
    time.Sleep(50 * time.Millisecond)

    assert.ErrorIs(t, parent.Err(), context.Canceled)
    assert.ErrorIs(t, child.Err(), context.Canceled)
}

Even though only parentCancel() was called, child.Err() also becomes context.Canceled. This is the essence of context propagation.

3.3 Use in the worker Pattern

This is the most commonly used pattern in practice. A worker goroutine watches ctx.Done() with select and terminates cleanly when a cancellation signal arrives.

func TestCancelWorker(t *testing.T) {
    ctx, cancel := context.WithCancel(context.Background())
    results := make(chan int, 10)

    // worker: works until canceled
    go func() {
        defer close(results)
        for i := 0; ; i++ {
            select {
            case <-ctx.Done():
                return
            case results <- i:
                time.Sleep(10 * time.Millisecond)
            }
        }
    }()

    // cancel after 50ms
    time.Sleep(50 * time.Millisecond)
    cancel()

    var collected []int
    for v := range results {
        collected = append(collected, v)
    }

    t.Logf("collected values: %v", collected)
    assert.Greater(t, len(collected), 0)
}

The worker loops infinitely sending results to a channel, and when ctx.Done() closes, it exits via return. Since defer close(results) cleans up the channel too, range results terminates naturally.

4. WithTimeout and WithDeadline

4.1 The Difference Between timeout and deadline

Both cancel the context based on time, but the way they specify the time differs.

• WithTimeout(parent, duration): cancel after duration from now
• WithDeadline(parent, time): cancel at a specific time

Internally, WithTimeout calls WithDeadline(parent, time.Now().Add(timeout)). Ultimately it's the same mechanism.

func TestWithTimeout(t *testing.T) {
    ctx, cancel := context.WithTimeout(context.Background(), 50*time.Millisecond)
    defer cancel()

    select {
    case <-time.After(200 * time.Millisecond):
        t.Fatal("should have timed out")
    case <-ctx.Done():
        assert.ErrorIs(t, ctx.Err(), context.DeadlineExceeded)
    }
}

Since a 50ms timeout was set, ctx.Done() closes before the 200ms wait completes. When canceled by timeout, ctx.Err() returns context.DeadlineExceeded.

func TestWithDeadline(t *testing.T) {
    deadline := time.Now().Add(50 * time.Millisecond)
    ctx, cancel := context.WithDeadline(context.Background(), deadline)
    defer cancel()

    <-ctx.Done()
    assert.ErrorIs(t, ctx.Err(), context.DeadlineExceeded)

    // check the expiration time with the Deadline() method
    dl, ok := ctx.Deadline()
    assert.True(t, ok)
    assert.Equal(t, deadline, dl)
}

WithDeadline uses an absolute time. You can look up the set expiration time with the Deadline() method.

4.2 Nested Timeout (when the inner one is shorter)

When nesting timeouts, the shorter timeout always takes precedence. Even if the inner context expires first, the outer context is unaffected.

func TestNestedTimeout(t *testing.T) {
    outer, outerCancel := context.WithTimeout(context.Background(), 200*time.Millisecond)
    defer outerCancel()

    inner, innerCancel := context.WithTimeout(outer, 50*time.Millisecond)
    defer innerCancel()

    <-inner.Done()

    // inner times out first
    assert.ErrorIs(t, inner.Err(), context.DeadlineExceeded)
    // outer is still alive
    assert.NoError(t, outer.Err())
}

outer is 200ms, inner is 50ms. inner expires first, but outer is still valid. This pattern is like putting a shorter timeout on a DB query (inner) inside an HTTP handler (outer).

What if the inner's timeout is longer than the outer's? In that case too, if outer is canceled first, inner is canceled along with it. A parent's cancellation always propagates to its children.

5. WithValue - Passing Request-Scoped Values

5.1 Basic Usage

context.WithValue stores a key-value pair in the context. It's mainly used to pass request-scoped data such as request IDs, authentication tokens, and tracing information.

func TestWithValue(t *testing.T) {
    ctx := context.Background()
    ctx = context.WithValue(ctx, userIDKey, "user-123")
    ctx = context.WithValue(ctx, requestIDKey, "req-456")

    // look up values
    userID := ctx.Value(userIDKey).(string)
    requestID := ctx.Value(requestIDKey).(string)

    assert.Equal(t, "user-123", userID)
    assert.Equal(t, "req-456", requestID)
}

Looking up a non-existent key returns nil. So it's safe to do a nil check before a type assertion.

5.2 Preventing Collisions with a typed key

If you use string directly as a context key, different packages might use the same string as a key, causing a collision. Defining a private type as the key prevents this problem.

// define type-safe context keys
type contextKey string

const (
    userIDKey    contextKey = "userID"
    requestIDKey contextKey = "requestID"
)

contextKey is based on string but is a distinct type, so even if another package accesses it as string("userID"), the types differ and won't match. This is the standard pattern for preventing context key collisions in Go.

5.3 value chain (looking up parent -> child values)

A context value is searched toward the parent along the tree. When you look up a value in a child context, if it's not on the child, it checks the parent, and if not on the parent, its parent, in order.

func TestWithValueChain(t *testing.T) {
    parent := context.WithValue(context.Background(), userIDKey, "parent-user")
    child := context.WithValue(parent, requestIDKey, "child-req")

    // can access the parent's value from the child
    assert.Equal(t, "parent-user", child.Value(userIDKey))
    assert.Equal(t, "child-req", child.Value(requestIDKey))

    // cannot access the child's value from the parent
    assert.Nil(t, parent.Value(requestIDKey))
}

The child can access the parent's userIDKey value, but the parent cannot access the child's requestIDKey value. Value lookup always proceeds from bottom to top (from child toward parent).

6. Context Propagation Patterns

6.1 parent cancellation -> all children canceled

If you create multiple child goroutines from a single root context, you can clean up all goroutines at once just by canceling the root.

func TestPropagation(t *testing.T) {
    root, rootCancel := context.WithCancel(context.Background())

    var stopped atomic.Int64

    // create 3 child goroutines
    for i := range 3 {
        child, childCancel := context.WithCancel(root)
        defer childCancel()

        go func() {
            <-child.Done()
            stopped.Add(1)
            t.Logf("child %d stopped", i)
        }()
    }

    rootCancel() // cancel root → all children canceled
    time.Sleep(50 * time.Millisecond)

    assert.Equal(t, int64(3), stopped.Load())
}

A single rootCancel() cleans up all 3 child goroutines. This is the power of context propagation. In an HTTP server, when a client disconnects, you can clean up all goroutines derived from that request with this pattern.

6.2 Pass context as the function's first parameter (Go convention)

There's a convention established in the Go community. Pass context as the function's first parameter, and use ctx as the variable name.

// worker - a function that takes context as the first parameter (Go convention)
func worker(ctx context.Context, id int, results chan<- string) {
    for {
        select {
        case <-ctx.Done():
            results <- fmt.Sprintf("worker %d: stopped", id)
            return
        case <-time.After(10 * time.Millisecond):
            results <- fmt.Sprintf("worker %d: working", id)
        }
    }
}

Using this worker function with a WaitGroup enables clean goroutine management.

func TestContextAsFirstParam(t *testing.T) {
    ctx, cancel := context.WithTimeout(context.Background(), 50*time.Millisecond)
    defer cancel()

    results := make(chan string, 100)

    var wg sync.WaitGroup
    wg.Add(2)
    go func() { defer wg.Done(); worker(ctx, 1, results) }()
    go func() { defer wg.Done(); worker(ctx, 2, results) }()

    // close the channel after all workers terminate
    go func() {
        wg.Wait()
        close(results)
    }()

    var messages []string
    for msg := range results {
        messages = append(messages, msg)
    }

    t.Logf("messages: %v", messages)
    assert.Greater(t, len(messages), 0)
}

It sets a 50ms limit with WithTimeout, waits for all workers to terminate with a WaitGroup, and then closes the channel. Combining context and WaitGroup lets you safely manage "parallel work with a time limit."

7. Best Practices

7.1 Don't Abuse context.Value

context.Value is convenient, but it should not be used to replace function signatures.

// bad example: putting function parameters into context
ctx = context.WithValue(ctx, "dbConn", db)
ctx = context.WithValue(ctx, "logger", log)

// good example: use explicit parameters
func HandleRequest(ctx context.Context, db *sql.DB, log *slog.Logger) {
    // ...
}

Data suitable for context.Value is request-scoped and hard to put in a function signature. Typical examples are request IDs, tracing spans, and authentication tokens.

7.2 Don't Store context in a struct

// bad example
type Server struct {
    ctx context.Context // don't store in a struct
}

// good example: pass as a method parameter
func (s *Server) HandleRequest(ctx context.Context) {
    // ...
}

A context should exist together with the request's lifecycle. Storing it in a struct makes it ambiguous which request's context it is, and cancellation propagation may not work properly.

7.3 Always Call cancel() with defer

The cancel function returned by WithCancel, WithTimeout, and WithDeadline must be called. If you don't call it, context-related resources won't be released, causing a memory leak.

ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
defer cancel() // always call with defer

// do work...

Even when the timeout expires and it's automatically canceled, it's safe to call cancel(). Calling cancel() on an already-canceled context does nothing (idempotent).

8. Wrapping Up

The core principles of the context package can be summarized as follows.

• pass context as the function's first parameter
• call cancel() immediately with defer
• a parent's cancellation propagates to all children
• context.Value stores only request-scoped data
• pass context as a parameter, not in a struct

context is the core tool for managing the goroutine lifecycle in Go. It's especially essential in server programming when implementing request handling, timeout management, and graceful shutdown.

9. FAQ

Q. How is the cancel() function implemented internally?

The cancel() function returned by context.WithCancel is defined on the cancelCtx struct in the Go standard library (go/src/context/context.go).

// cancelCtx - the internal struct of a cancelable context
type cancelCtx struct {
    Context                        // embeds the parent context
    mu       sync.Mutex            // mutex to protect concurrent access
    done     atomic.Value          // stores chan struct{}, lazily created on first call
    children map[canceler]struct{} // list of child contexts (for cancellation propagation)
    err      error                 // cancellation reason (Canceled or DeadlineExceeded)
    cause    error                 // Go 1.20+ cause chain
}

// cancel - the actual cancellation logic
func (c *cancelCtx) cancel(removeFromParent bool, err, cause error) {
    c.mu.Lock()

    if c.err != nil {
        c.mu.Unlock()
        return // ignore if already canceled (guarantees idempotency)
    }

    c.err = err     // set context.Canceled
    c.cause = cause

    // close the done channel to wake goroutines waiting on <-ctx.Done()
    d, _ := c.done.Load().(chan struct{})
    if d == nil {
        c.done.Store(closedchan) // if not yet created, store a pre-closed channel
    } else {
        close(d) // close the existing channel → all receivers wake up immediately
    }

    // recursively cancel all child contexts too
    for child := range c.children {
        child.cancel(false, err, cause)
    }
    c.children = nil
    c.mu.Unlock()

    if removeFromParent {
        removeChild(c.Context, c) // remove itself from the parent's children map
    }
}

The core behavior can be summarized as follows.

close(d) is the key — in Go, a closed channel immediately returns the zero value, so all goroutines waiting on <-ctx.Done() wake up simultaneously. This is why context's cancellation propagation is efficient.

Q. How should I set the context timeout when calling a DB / external API from an API handler?

When an API handler calls a DB query or an external API, if a problem occurs at any layer, the entire request can stall. To prevent this, you need to set context timeouts appropriately.

Method 1: a single timeout for the entire request

// resty client (reused at the package level)
var client = resty.New()

func handler(w http.ResponseWriter, r *http.Request) {
    ctx, cancel := context.WithTimeout(r.Context(), 5*time.Second) // 5-second limit for the whole thing
    defer cancel()

    // DB query — interrupted when ctx is canceled
    user, err := db.GetUser(ctx, userID)
    if err != nil { return }

    // external API call — pass the same ctx to resty
    var profile Profile
    _, err = client.R().
        SetContext(ctx).           // propagate the context
        SetResult(&profile).
        Get(fmt.Sprintf("https://api.example.com/profile/%s", user.Email))
    if err != nil { return }
}

It's simple, but it has the problem that if the DB takes 4.5 seconds, the external API has only 0.5 seconds.

Method 2: per-layer individual timeouts (recommended)

func handler(w http.ResponseWriter, r *http.Request) {
    ctx := r.Context() // the parent context

    // 2-second limit for the DB
    dbCtx, dbCancel := context.WithTimeout(ctx, 2*time.Second)
    defer dbCancel()
    user, err := db.GetUser(dbCtx, userID)
    if err != nil { return }

    // 3-second limit for the external API — pass an individual context to resty
    apiCtx, apiCancel := context.WithTimeout(ctx, 3*time.Second)
    defer apiCancel()

    var profile Profile
    _, err = client.R().
        SetContext(apiCtx).        // per-layer timeout context
        SetResult(&profile).
        Get(fmt.Sprintf("https://api.example.com/profile/%s", user.Email))
    if err != nil { return }
}

By giving each layer an appropriate timeout, a slowdown in one doesn't affect the other layers. resty's SetContext() internally calls http.Request.WithContext(), so when a timeout or cancel occurs, even the TCP connection is interrupted immediately.

Method 3: parallel calls + errgroup (when the calls are independent)

If the DB and external API are independent of each other, you can call them in parallel and cancel the rest if any one fails.

func handler(w http.ResponseWriter, r *http.Request) {
    ctx, cancel := context.WithTimeout(r.Context(), 5*time.Second)
    defer cancel()

    g, gCtx := errgroup.WithContext(ctx) // any error → the rest are automatically canceled

    var user *User
    var profile Profile

    g.Go(func() error {
        var err error
        user, err = db.GetUser(gCtx, userID) // use gCtx
        return err
    })

    g.Go(func() error {
        _, err := client.R().
            SetContext(gCtx).      // errgroup's context → auto-canceled when another goroutine fails
            SetResult(&profile).
            Get(fmt.Sprintf("https://api.example.com/profile/%s", email))
        return err
    })

    if err := g.Wait(); err != nil { return }
}

How resty's SetContext() works internally: when you call SetContext(ctx), resty internally uses the Go standard library's http.Request.WithContext(ctx). This context propagates down to the roundTrip() step of net/http.Transport, so when the context is canceled, it's immediately interrupted at every step of the HTTP request — DNS lookup, TCP connection, TLS handshake, response reading. Therefore, as long as you pass SetContext(ctx) correctly, unnecessary network resources are immediately released on timeout or cancel.

// inside resty (simplified)
func (r *Request) Execute(method, url string) (*Response, error) {
    // 1. create an http.Request
    req, _ := http.NewRequestWithContext(r.ctx, method, url, body)

    // 2. call http.Client.Do() — immediately interrupted when the context is canceled
    resp, err := r.client.httpClient.Do(req)
    // returns a context.DeadlineExceeded or context.Canceled error
}

Q. How do I manage timeouts in the Echo framework?

Echo has a built-in TimeoutMiddleware, so you can automatically apply a timeout to all handlers.

import "github.com/labstack/echo/v4/middleware"

e := echo.New()

// apply a 5-second timeout to all handlers
e.Use(middleware.TimeoutWithConfig(middleware.TimeoutConfig{
    Timeout: 5 * time.Second,
}))

In a handler, use the timeout context set by the middleware via c.Request().Context().

func getUser(c echo.Context) error {
    ctx := c.Request().Context() // the timeout context set by the middleware

    user, err := db.GetUser(ctx, id)
    if err != nil {
        if errors.Is(err, context.DeadlineExceeded) {
            return echo.NewHTTPError(http.StatusGatewayTimeout, "request timed out")
        }
        return err
    }
    return c.JSON(http.StatusOK, user)
}

You can also set a different timeout per route.

// default 5 seconds
e.Use(middleware.TimeoutWithConfig(middleware.TimeoutConfig{
    Timeout: 5 * time.Second,
}))

// 30 seconds only for the file upload route
uploadGroup := e.Group("/upload")
uploadGroup.Use(middleware.TimeoutWithConfig(middleware.TimeoutConfig{
    Timeout: 30 * time.Second,
}))

The middleware is the upper limit for the entire request, while per-layer granularity (DB 2 seconds, external API 3 seconds) is, as a practical pattern, set directly inside the handler with context.WithTimeout.

10. References

• Example code: tutorials-go/golang/concurrency/context
• Go official docs - context package
• Go Blog - Contexts and structs
• Go Concurrency Patterns: Context

In this part, we cover how to use the core tools of the sync package — WaitGroup, Mutex, RWMutex, Once, and sync.Map — and when to apply each.

1. Why Do We Need Synchronization?

When multiple goroutines access the same variable simultaneously, a race condition occurs. A race condition is the phenomenon where, when two or more goroutines access a shared resource at the same time, the result varies depending on the execution order. It creates non-deterministic bugs where the program sometimes works correctly and sometimes produces wrong results.

// dangerous code: accessing a shared variable without protection
counter := 0
for range 1000 {
    go func() {
        counter++ // Data Race! values are lost when multiple goroutines read and write simultaneously
    }()
}
// expected: 1000, actual: different every time (e.g. 937, 982, 1000...)

counter++ is actually a 3-step operation: "read → increment → write." When multiple goroutines run it simultaneously, values are lost. For example, if two goroutines read the counter value 5 at the same time and each write 6, it incremented twice but the result is 6.

Running with go test -race or go run -race lets Go's Race Detector detect data races. Always perform race checks on production code.

2. sync.WaitGroup

The most basic tool for waiting on the completion of multiple goroutines. It maintains a counter internally, incrementing it with Add() and decrementing it with Done(). Wait() blocks until the counter reaches 0.

You can also wait for goroutine completion with a channel, but for simply "waiting until all N goroutines finish," WaitGroup is far more concise.

var wg sync.WaitGroup

for i := range 5 {
    wg.Add(1)        // counter +1: must be called before starting the goroutine
    go func() {
        defer wg.Done() // counter -1: called when the goroutine completes (defer makes it panic-safe)
        // do work
    }()
}

wg.Wait() // block until the counter reaches 0 (wait for all goroutines to complete)

Key rule: wg.Add() must be called before the go statement. If you Add inside the goroutine, Wait() may run first.

WaitGroup is reusable. However, you must call Add() again after Wait() returns. Calling Add() while Wait() is running causes a panic.

3. sync.Mutex

Guarantees mutual exclusion. Only one goroutine can access the critical section at a time. Only the goroutine that called Lock() monopolizes that section until it calls Unlock(). Other goroutines, when they call Lock(), wait until the existing goroutine calls Unlock().

Bundling a Mutex into a struct together with the data it protects is Go's idiomatic pattern. This makes it clear in the code "which lock protects which data."

func TestMutexCriticalSection(t *testing.T) {
    // bundling the Mutex and the data it protects into a single struct is Go's idiomatic pattern
    type SafeCounter struct {
        mu sync.Mutex
        v  map[string]int
    }

    c := SafeCounter{v: make(map[string]int)}
    var wg sync.WaitGroup

    for range 100 {
        wg.Add(1)
        go func() {
            defer wg.Done()
            c.mu.Lock()   // enter the critical section: other goroutines wait here
            c.v["key"]++  // protected section: only one goroutine runs at a time
            c.mu.Unlock() // release the critical section: a waiting goroutine can enter
        }()
    }

    wg.Wait()
    assert.Equal(t, 100, c.v["key"]) // exactly 100 thanks to Mutex protection
}

Best Practice: using defer mu.Unlock() releases the lock even if a panic occurs. It's especially useful when the critical section is long or there are multiple return points.

A Mutex must not be copied. When passing it to a function, always pass a pointer. go vet detects Mutex copies.

4. sync.RWMutex

A Mutex forces all access — read or write — to run one at a time without distinction. But read operations don't change data, so multiple goroutines can safely read simultaneously. RWMutex leverages this to greatly improve read performance.

A read lock (RLock) can be acquired simultaneously by multiple goroutines. The write lock (Lock) is exclusive. While a write is in progress, all reads/writes wait; while a read is in progress, only writes wait.

var rwmu sync.RWMutex

// multiple readers can run simultaneously — improves read performance
rwmu.RLock()        // acquire read lock: other readers can also acquire simultaneously
_ = data["key"]     // read data (no modification)
rwmu.RUnlock()      // release read lock

// the writer is exclusive — both reads and writes block
rwmu.Lock()             // acquire write lock: all readers/writers wait
data["key"] = "updated" // modify data
rwmu.Unlock()           // release write lock

When reads are frequent and writes are rare, RWMutex performs better than Mutex. For example, it's a good fit for scenarios like caches, config lookups, and read APIs where reads are 90%+ and writes are 10% or less.

If writes are frequent, RWMutex may actually be slower than a plain Mutex due to its internal overhead. Choose after verifying with a benchmark.

5. sync.Once

Guarantees that a function runs exactly once. Even if multiple goroutines call once.Do() simultaneously, the passed function runs exactly once, and the remaining goroutines wait until execution completes.

It's most useful when you want to lazily perform an expensive initialization (DB connection pool initialization, config file loading, etc.) while making it goroutine-safe. Unlike an init() function, the initialization runs at the point it's actually needed.

func TestOnceSingleton(t *testing.T) {
    type Config struct {
        DBHost string
        DBPort int
    }

    var (
        instance *Config   // the singleton instance to be initialized only once
        once     sync.Once // guarantees the initialization function runs exactly once
    )

    getConfig := func() *Config {
        once.Do(func() { // no matter how many times this is called, it runs exactly once
            instance = &Config{
                DBHost: "localhost",
                DBPort: 5432,
            }
        })
        return instance // after initialization, immediately return the cached instance
    }

    // returns the same instance even when called simultaneously from multiple goroutines
    var wg sync.WaitGroup
    results := make([]*Config, 10)

    for i := range 10 {
        wg.Add(1)
        go func() {
            defer wg.Done()
            results[i] = getConfig() // 10 goroutines call simultaneously
        }()
    }

    wg.Wait()

    for i := 1; i < len(results); i++ {
        assert.Same(t, results[0], results[i]) // all the same pointer — initialization ran only once
    }
}

Even if a panic occurs inside once.Do(), it is considered "executed once." The function won't run again on subsequent calls, so be careful with error handling inside the initialization function.

6. sync.Map

Go's regular map is not concurrent-safe. If multiple goroutines read and write a map simultaneously, a fatal error: concurrent map writes runtime panic occurs. sync.Map uses a lock-free algorithm and a read-only cache internally, enabling concurrent access without a separate lock.

sync.Map does not support generics, so it operates with the any type. A downside is that you need a type assertion when retrieving values.

var m sync.Map

m.Store("key", "value")                   // store: add a key-value pair
val, ok := m.Load("key")                  // load: returns the value and whether it exists
m.Delete("key")                            // delete: remove a key
actual, loaded := m.LoadOrStore("k", "v")  // store if absent, return the existing value if present

// iterate: run a function for every key-value
m.Range(func(key, value any) bool {
    fmt.Println(key, value)
    return true // true: continue to the next item, false: stop iteration
})

So which should you choose between a regular map + Mutex and sync.Map?

In most cases, the map + RWMutex combination is more general-purpose. sync.Map shines in cache scenarios where keys are rarely changed once set.

7. Wrapping Up

In this part, we looked at the core synchronization primitives provided by Go's sync package. Each tool has its own purpose, and it's important to choose the right one for the situation.

So which should you choose between Channel and Mutex? The official Go Wiki recommends "Channel for transferring ownership of data, Mutex for protecting the internal state of a struct." Refer to the table below to choose the right tool for the situation.

In practice, rather than sticking to a single tool, it's better to combine them to fit the situation. For example, the pattern of waiting for goroutine completion with WaitGroup while protecting shared data with Mutex is very common. The important thing is to make a habit of always verifying data races with go test -race.

In the next part, we'll cover the Context package, the core tool for managing the goroutine lifecycle.

8. References

• Go Blog - Share Memory By Communicating
• sync package docs

When managing infrastructure, you often run into the question: "Who changed this server setting, when, and why?" You click around in the console manually, type commands into the CLI, and try to document the process, but eventually a gap appears between the actual state and the documentation.

IaC (Infrastructure as Code) solves this problem. When you define infrastructure as code:

• Version control: You can track change history with Git
• Reproducibility: Running the same code produces the same environment
• Code review: Infrastructure changes can also be reviewed via PRs
• Automation: It can be integrated into CI/CD pipelines

1.1 Why Terraform

There are several IaC tools available.

The reasons for choosing Terraform are as follows:

• Declarative approach: You define "what" you want rather than "how." Terraform calculates the difference between the current state and the desired state and applies it
• Provider ecosystem: There are thousands of Providers, including AWS, GCP, and Azure, as well as Kubernetes, Helm, Docker, GitHub, and more
• Plan feature: You can preview what changes will occur before actually applying them
• Community: As the most widely used IaC tool, it has abundant resources and modules

In this article, after understanding Terraform's basic concepts, we will walk through a hands-on exercise of deploying ArgoCD to a Kind cluster. Finally, I introduce the Terraform + ArgoCD + Helm combination that I actually use.

The full source code is available on GitHub.

2. Terraform Basic Concepts

2.1 HCL (HashiCorp Configuration Language)

Terraform uses its own configuration language called HCL. It is easier to read than JSON and has clearer typing than YAML.

# Basic syntax structure
resource "resource_type" "name" {
  attribute1 = "value"
  attribute2 = 123

  nested_block {
    attribute3 = true
  }
}

Key characteristics of HCL:

• Block-based: Organized into block units wrapped in {}
• Attribute assignment: Values are assigned with =
• Comments: Use # or //
• String interpolation: You can reference variables like "${var.name}" (for simple references, var.name is sufficient)

2.2 Core Components

The core components of Terraform can be summarized as follows. The order below is arranged based on dependencies and learning flow. You need a Provider to create Resources, you configure Resources flexibly with Variables/Outputs, you query existing resources with Data Sources, and you bundle all of this into reusable units with Modules.

flowchart LR
    subgraph "Terraform Components"
        P[Provider] --> R[Resource]
        P --> D[Data Source]
        V[Variable] --> R
        R --> O[Output]
        R --> M[Module]
    end

2.2.1 Provider

A Provider is a plugin that allows Terraform to communicate with external services. There is a Provider for each service, such as AWS, Kubernetes, and Helm. A Provider is the starting point for everything—without a Provider, you cannot create Resources. When you run terraform init, the declared Providers are downloaded automatically, and by pinning versions, the entire team can work in an identical environment.

# Provider declaration
terraform {
  required_providers {
    kind = {
      source  = "tehcyx/kind"    # Provider source
      version = "0.8"            # Version constraint
    }
    kubernetes = {
      source  = "hashicorp/kubernetes"
      version = "2.36"
    }
  }
}

# Provider configuration
provider "kubernetes" {
  config_path = kind_cluster.local_cluster.kubeconfig_path
}

2.2.2 Resource

A Resource is an actual infrastructure object that Terraform creates and manages. It is declared in the form resource "type" "name". Any infrastructure supported by a Provider—servers, networks, databases, and so on—can be defined as a Resource, and Terraform manages the entire lifecycle from creation to modification to deletion.

# Kind cluster resource declaration
resource "kind_cluster" "local_cluster" {
  name           = var.kind_cluster_name
  wait_for_ready = true
  node_image     = "kindest/node:v1.28.15"
}

# Kubernetes Namespace resource declaration
resource "kubernetes_namespace" "study" {
  depends_on = [kind_cluster.local_cluster]
  metadata {
    name = var.study_namespace
  }
}

• kind_cluster.local_cluster: A unique identifier combining the resource type and name
• depends_on: An explicit dependency declaration between resources (in this case, the cluster must be created first)

2.2.3 Variable and Output

Variable allows configuration values to be injected from the outside, and Output outputs the generated results. Using Variables, you can apply different values per environment (dev/staging/prod), and Output is useful when other modules or scripts need to reference information about created resources.

# Variable: input value definition
variable "kind_cluster_name" {
  description = "Kind cluster name"
  type        = string
  default     = "terraform-study-cluster"
}

# Output: result value output
output "kubeconfig_path" {
  description = "Path to the Kind cluster's kubeconfig file"
  value       = kind_cluster.local_cluster.kubeconfig_path
}

How to override a Variable value:

# CLI argument
terraform apply -var="kind_cluster_name=my-cluster"

# Environment variable
export TF_VAR_kind_cluster_name="my-cluster"

# terraform.tfvars file
kind_cluster_name = "my-cluster"

2.2.4 Data Source

A Data Source reads information about resources that already exist outside of Terraform. If a Resource is about "creating," a Data Source is about "querying." For example, you can fetch information about a VPC or Namespace that was already created manually and reference it from other resources, naturally connecting existing infrastructure with new resources.

# Query information about an existing Namespace
data "kubernetes_namespace" "default" {
  metadata {
    name = "default"
  }
}

# Use the queried information
resource "kubernetes_config_map" "example" {
  metadata {
    namespace = data.kubernetes_namespace.default.metadata[0].name
  }
}

2.2.5 Module

A Module bundles related resources into a single reusable package. By separating them into directory units, it improves code organization and reusability. You can use community modules published on the Terraform Registry, or you can turn common in-house infrastructure patterns into modules and use them consistently across multiple projects.

# Module call (main.tf)
module "infra" {
  source          = "./modules/infra"            # Module path
  study_namespace = kubernetes_namespace.study.metadata[0].name  # Pass variable

  depends_on = [kubernetes_namespace.study]
}

# Inside the module (modules/infra/infra.tf)
# - Create resources using the passed-in variables
resource "helm_release" "argocd" {
  name       = "argocd"
  repository = "https://argoproj.github.io/argo-helm"
  chart      = "argo-cd"
  version    = "7.8.28"
  namespace  = kubernetes_namespace.argocd.metadata[0].name
  # ...
}

2.3 State (State Management)

Terraform records the current state of infrastructure in a State file (terraform.tfstate). This file is the heart of Terraform.

flowchart LR
    A[".tf files\n(desired state)"] --> C{Terraform}
    B["terraform.tfstate\n(current state)"] --> C
    C --> D["Plan\n(change plan)"]
    D --> E["Apply\n(actual changes)"]
    E --> B

• During Plan: Compares the .tf files (desired state) and the State file (current state) to calculate the differences
• During Apply: Applies the calculated changes to the actual infrastructure and updates the State file

State management methods:

Note: The State file may contain sensitive information such as passwords and API keys. Be sure to add it to .gitignore, and use a Remote Backend in team environments.

3. Architecture

3.1 How Terraform Works

The Terraform workflow consists of four stages.

flowchart LR
    A["**Init**\nDownload Providers\nCreate .terraform/"] --> B["**Plan**\nPreview changes\n+ create, ~ modify, - delete"]
    B --> C["**Apply**\nApply to real infrastructure\nUpdate State"]
    C --> D["**Destroy**\nDelete all resources\nReset State"]

    style A fill:#e1f5fe
    style B fill:#fff3e0
    style C fill:#e8f5e9
    style D fill:#ffebee

3.2 Provider Plugin Architecture

Terraform Core is responsible for HCL parsing and state management, while the actual infrastructure manipulation is performed by Provider Plugins.

flowchart TB
    subgraph "Terraform Core"
        A[HCL Parser] --> B[Dependency Graph]
        B --> C[State Management]
    end

    subgraph "Provider Plugins (gRPC)"
        D[Kind Provider]
        E[Kubernetes Provider]
        F[Helm Provider]
    end

    C --> D
    C --> E
    C --> F

    D --> G[Docker - Kind cluster]
    E --> H[K8s API Server]
    F --> I[Helm chart deployment]

• Providers are separate binaries that communicate with Terraform Core via gRPC
• When you run terraform init, the required Providers are downloaded automatically
• By pinning Provider versions, reproducible builds are guaranteed

3.3 Dependency Graph

Terraform manages dependency relationships between resources as a DAG (Directed Acyclic Graph). Resources without dependencies are created in parallel, which speeds things up.

flowchart TD
    A[kind_cluster.local_cluster] --> B[kubernetes_namespace.study]
    A --> C[Provider initialization\nkubernetes, helm]
    B --> D[null_resource.set_default_namespace]
    B --> E[module.infra]
    E --> F[helm_release.ingress-nginx]
    E --> G[helm_release.argocd]

    style A fill:#e1f5fe
    style E fill:#fff3e0

In the graph above, the Kind cluster is created first, and then the Namespace and Provider initialization proceed in parallel. After that, Ingress-NGINX and ArgoCD inside the infra module are also installed in parallel.

You can view the dependency graph with the following command:

terraform graph | dot -Tpng > graph.png

4. Installation and Basic Usage

4.1 Installation

On macOS, installing via Homebrew is the simplest.

# Install via Homebrew
brew install terraform

# Check version
terraform version

If you need to use different Terraform versions across multiple projects, tfenv (a version manager) is recommended.

# Install tfenv
brew install tfenv

# Install and use a specific version
tfenv install 1.10.0
tfenv use 1.10.0

# Check the currently used version
tfenv list

4.2 Key CLI Commands

The commonly used commands can be summarized as follows.

# Initialize: download Providers and install modules
terraform init
terraform init -upgrade    # Upgrade Providers to the latest allowed version

# Code validation and formatting
terraform validate         # Validate configuration file syntax
terraform fmt              # Automatically format code (to the standard style)
terraform fmt -check       # Only check whether formatting changes are needed

# Review the change plan
terraform plan             # Preview which resources will be created/modified/deleted

# Apply
terraform apply            # Apply changes (shows a confirmation prompt)
terraform apply -auto-approve  # Apply immediately without confirmation

# Check state
terraform show             # Detailed information about resources in the current State
terraform output           # Output the Output values
terraform state list       # List of managed resources

# Delete
terraform destroy          # Delete all resources
terraform destroy -target=kind_cluster.local_cluster  # Delete only a specific resource

4.3 File Structure Convention

A Terraform project usually separates files as follows.

project/
├── main.tf          # Provider configuration, module calls
├── variables.tf     # Variable definitions
├── outputs.tf       # Output definitions
├── terraform.tfvars # Variable values (optional, target for .gitignore)
├── modules/         # Reusable modules
│   └── infra/
│       ├── infra.tf
│       └── variables.tf
└── .gitignore       # Exclude State, Provider cache

Items that should be included in .gitignore:

.terraform/          # Provider binary cache
*.tfstate            # State files
*.tfstate.backup     # State backups
*.tfvars             # Sensitive variable values

5. Hands-on: Deploying a Kind Cluster + ArgoCD

The hands-on code is available at tutorials-go/cloud/terraform. In this exercise, we will go through the process of creating a local Kubernetes cluster with Terraform and installing ArgoCD.

5.1 Hands-on Goals and Architecture

flowchart TB
    subgraph "Resources created by Terraform"
        A[Kind cluster\n1 Control Plane + 2 Workers]
        B[study Namespace]
        C[Ingress-NGINX\nHelm deployment]
        D[ArgoCD\nHelm deployment]
    end

    A --> B
    A --> C
    A --> D

5.2 Step 1: Provider Configuration (main.tf)

First, declare the Providers you will use.

terraform {
  required_providers {
    kind = {
      source  = "tehcyx/kind"
      version = "0.8"
    }
    kubernetes = {
      source  = "hashicorp/kubernetes"
      version = "2.36"
    }
    helm = {
      source  = "hashicorp/helm"
      version = "3.0.0-pre2"
    }
    null = {
      source = "hashicorp/null"
    }
  }
}

The Kubernetes and Helm Providers connect by referencing the Kind cluster's kubeconfig.

provider "kubernetes" {
  config_path = kind_cluster.local_cluster.kubeconfig_path
}

provider "helm" {
  kubernetes = {
    config_path = kind_cluster.local_cluster.kubeconfig_path
  }
}

5.3 Step 2: Create the Kind Cluster (kind.tf)

Define the Kind cluster. It consists of 1 Control Plane and 2 Worker nodes.

resource "kind_cluster" "local_cluster" {
  name           = var.kind_cluster_name
  wait_for_ready = true
  node_image     = "kindest/node:v1.28.15"

  kind_config {
    kind        = "Cluster"
    api_version = "kind.x-k8s.io/v1alpha4"

    node {
      role = "control-plane"
      extra_port_mappings {
        container_port = 30080
        host_port      = 30080
        listen_address = "127.0.0.1"
      }
      extra_mounts {
        host_path      = "/tmp/kind-storage"
        container_path = "/opt/local-path-provisioner"
      }
    }

    node { role = "worker" }
    node { role = "worker" }
  }
}

• extra_port_mappings: Maps ports so that NodePort services can be accessed from the host
• extra_mounts: Stores Persistent Volume data on the host disk

5.4 Step 3: Deploy ArgoCD with a Module (modules/infra/)

The infrastructure installation is separated into a module for management. The module is called from main.tf.

module "infra" {
  source          = "./modules/infra"
  study_namespace = kubernetes_namespace.study.metadata[0].name

  depends_on = [kubernetes_namespace.study]
}

Inside the module, ArgoCD is installed using the Helm Provider.

# modules/infra/infra.tf
resource "helm_release" "argocd" {
  name       = "argocd"
  repository = "https://argoproj.github.io/argo-helm"
  chart      = "argo-cd"
  version    = "7.8.28"
  namespace  = kubernetes_namespace.argocd.metadata[0].name

  values = [
    <<-EOT
    configs:
      secret:
        argocdServerAdminPassword: ${var.argocd_password}
    server:
      service:
        type: "ClusterIP"
    EOT
  ]
}

helm_release performs the same operation as helm install. In the values block, you can define Helm values inline.

5.5 Step 4: Run and Verify

# 1. Initialize
make tf-init

# 2. Preview changes with Plan
terraform plan

# 3. Apply
make tf-install

# 4. Check the created resources
kubectl get nodes
kubectl get pods -n argocd

# 5. Access the ArgoCD UI (port forwarding)
kubectl port-forward svc/argocd-server -n argocd 8080:443
# Access https://localhost:8080 in your browser
# ID: admin / PW: password

When you run terraform plan, the resources to be created are displayed as follows:

Plan: 7 to add, 0 to change, 0 to destroy.

5.6 Step 5: Deploy an Application with ArgoCD

Now that the cluster and ArgoCD are ready with Terraform, let's register and deploy an application in ArgoCD. We will use bootstrap/sample-apps.yaml and charts/sample-nginx/ included in the sample code.

Helm Chart Structure

First, let's look at the Helm chart structure of the sample NGINX app to be deployed.

charts/sample-nginx/
├── Chart.yaml           # Chart metadata
├── values.yaml          # Definition of settings like image, replica count, resources
└── templates/
    ├── deployment.yaml  # K8s Deployment template that references settings via {{ .Values.xxx }}
    └── service.yaml     # K8s Service template

Registering Apps in ArgoCD with an ApplicationSet

When registering apps in ArgoCD, use an ApplicationSet. An ApplicationSet lets you define multiple Applications at once based on a template.

# bootstrap/sample-apps.yaml
apiVersion: argoproj.io/v1alpha1
kind: ApplicationSet
metadata:
  name: sample-apps
  namespace: argocd
spec:
  generators:
    - list:
        elements:
          - appName: sample-nginx      # List of apps to deploy
  template:
    metadata:
      name: "{{appName}}"
    spec:
      project: default
      source:
        repoURL: https://github.com/kenshin579/tutorials-go.git
        targetRevision: main
        path: "cloud/terraform/charts/{{appName}}"   # Helm chart path
      destination:
        server: https://kubernetes.default.svc
        namespace: study
      syncPolicy:
        automated:
          prune: true       # Resources deleted from Git are also deleted in K8s
          selfHeal: true    # Automatically restores to the Git state on manual changes
        syncOptions:
          - CreateNamespace=true

• generators.list.elements: The list of apps to deploy. To add a new app, just add an entry here
• source.path: The Helm chart path within the Git repository. {{appName}} is substituted with the actual app name
• syncPolicy.automated: When a change is detected in Git, it is automatically applied to K8s

Running and Verifying the Deployment

# 1. Apply the ApplicationSet
kubectl apply -f bootstrap/sample-apps.yaml

# 2. Check the ArgoCD Application status
kubectl get applications -n argocd
# NAME           SYNC STATUS   HEALTH STATUS
# sample-nginx   Synced        Healthy

# 3. Check the deployed Pods
kubectl get pods -n study
# NAME                            READY   STATUS    RESTARTS   AGE
# sample-nginx-xxxxx-xxxxx        1/1     Running   0          30s

# 4. Check the Service
kubectl get svc -n study
# NAME           TYPE        CLUSTER-IP     EXTERNAL-IP   PORT(S)   AGE
# sample-nginx   ClusterIP   10.96.x.x      <none>        80/TCP    30s

# 5. NGINX access test
kubectl port-forward svc/sample-nginx -n study 8081:80
# Access http://localhost:8081 in your browser

In the ArgoCD UI (https://localhost:8080), you can also confirm that the sample-nginx app is registered in the Synced/Healthy state.

Testing a Configuration Change

Let's verify ArgoCD's automatic synchronization. If you change the replica count in values.yaml and Git push, ArgoCD applies it automatically.

# Modify charts/sample-nginx/values.yaml
replicaCount: 2   # Change from 1 to 2

# After Git push, wait a moment and ArgoCD detects it automatically
kubectl get pods -n study
# NAME                            READY   STATUS    RESTARTS   AGE
# sample-nginx-xxxxx-aaaaa        1/1     Running   0          5m
# sample-nginx-xxxxx-bbbbb        1/1     Running   0          10s   ← newly created

Without touching the Terraform code at all, the deployment was completed by modifying only the Helm chart's values.yaml. This is the key advantage of the Terraform + ArgoCD + Helm combination.

5.7 Step 6: Cleanup

# Delete the ArgoCD Application
kubectl delete -f bootstrap/sample-apps.yaml

# Delete all Terraform resources (Kind cluster + ArgoCD)
make tf-destroy

# Clean up even the Terraform cache
make tf-clean

6. The Way I Use It: Terraform + ArgoCD + Helm

6.1 Why Minimize Terraform's Scope

You could manage all Kubernetes resources with Terraform. But in practice, the following problems arise:

• Increased State management complexity: As the number of apps grows, the State file becomes bloated and terraform plan slows down
• Deployment speed: Even changing the configuration of a single app requires checking the entire State
• Difficult role separation: Infrastructure engineers and app developers have to manage the same Terraform code

That's why I limit Terraform's role to the minimum.

6.2 Overall Structure

flowchart TB
    subgraph "Layer 1: Terraform"
        T1[Create Kind cluster]
        T2[Install ArgoCD via Helm]
        T1 --> T2
    end

    subgraph "Layer 2: ArgoCD"
        A1[ApplicationSet]
        A2[Watch Git repository]
        A1 --> A2
    end

    subgraph "Layer 3: Helm Charts"
        H1["sample-nginx"]
        H2["my-app-be"]
        H3["my-app-fe"]
    end

    T2 --> A1
    A2 --> H1
    A2 --> H2
    A2 --> H3

    H1 --> K1[K8s Deployment + Service]
    H2 --> K2[K8s Deployment + Service]
    H3 --> K3[K8s Deployment + Service]

The directory structure of the project I actually use is as follows.

charts/
├── main.tf                          # Provider configuration
├── k8s.tf                           # Kind cluster definition (1 CP + 3 Workers)
├── variables.tf
├── outputs.tf
├── modules/
│   └── infra/
│       └── infra.tf                 # Managed by Terraform: installs only ArgoCD
├── bootstrap/                       # ArgoCD ApplicationSet definitions
│   ├── macmini-infra.yaml           #   → DB (MySQL, Redis)
│   ├── macmini-app.yaml             #   → Apps (10+)
│   └── macmini-gateway.yaml         #   → Gateway (NGINX, cert-manager)
├── charts/                          # Collection of Helm charts (20+)
│   ├── mysql/                       #   infrastructure
│   ├── redis/
│   ├── nginx-gateway/
│   ├── cert-manager/
│   ├── inspireme-be/                #   applications
│   ├── inspireme-fe/
│   ├── moneyflow-be/
│   ├── moneyflow-fe/
│   ├── ai-chatbot-be/
│   └── ...
└── Makefile

The key point is that modules/infra/infra.tf installs only ArgoCD. Infrastructure DBs like MySQL and Redis and all applications are registered in ArgoCD via the ApplicationSet in bootstrap/, and the actual K8s resource definitions are managed in each Helm chart under charts/.

The core of this structure is the separation of concerns:

• Terraform: Only responsible for "the cluster exists and ArgoCD is installed"
• ArgoCD: Manages "which apps should be deployed"
• Helm Charts: Define "how each app is configured"

6.3 Real-World Workflow

The flow in actual operations is as follows.

sequenceDiagram
    participant Dev as Developer
    participant Git as Git Repository
    participant Argo as ArgoCD
    participant K8s as Kubernetes

    Dev->>Git: 1. Modify Helm values.yaml (image version, etc.)
    Dev->>Git: 2. Create PR → review → merge
    Git->>Argo: 3. ArgoCD detects the change (automatic)
    Argo->>K8s: 4. Render Helm chart → apply K8s resources
    K8s-->>Argo: 5. Synchronization complete (Healthy/Synced)

To change an app's configuration, you only need to modify the Helm chart's values.yaml. There is no need to touch the Terraform code.

ApplicationSet Example

When registering apps in ArgoCD, use an ApplicationSet. The following is an example included in the sample code.

apiVersion: argoproj.io/v1alpha1
kind: ApplicationSet
metadata:
  name: sample-apps
  namespace: argocd
spec:
  generators:
    - list:
        elements:
          - appName: sample-nginx
  template:
    metadata:
      name: "{{appName}}"
    spec:
      project: default
      source:
        repoURL: https://github.com/kenshin579/tutorials-go.git
        targetRevision: main
        path: "cloud/terraform/charts/{{appName}}"
      destination:
        server: https://kubernetes.default.svc
        namespace: study
      syncPolicy:
        automated:
          prune: true       # Resources deleted from Git are also deleted in K8s
          selfHeal: true    # Automatically restores to the Git state on manual changes

• generators.list: The list of apps to deploy. To add a new app, just add an entry here
• syncPolicy.automated: When ArgoCD detects a Git change, it is automatically applied to K8s

Helm Chart Example

Each app's Kubernetes resources are defined with a Helm chart.

# charts/sample-nginx/values.yaml
replicaCount: 1

image:
  repository: nginx
  tag: "1.27.0"

service:
  type: ClusterIP
  port: 80

resources:
  requests:
    cpu: 50m
    memory: 64Mi
  limits:
    cpu: 100m
    memory: 128Mi

If you want to change the replica count, just modify replicaCount in values.yaml and Git push, and ArgoCD applies it automatically.

6.4 Advantages of This Structure

1. The scope of changes is clear: App configuration is changed only in Helm Charts, and the cluster only in Terraform
2. The Terraform State is concise: Since it only manages the cluster and ArgoCD, the State is small and fast
3. ArgoCD detects drift: Even if someone manually changes a K8s resource, ArgoCD restores it to the original state
4. Adding an app is simple: Just create a Helm chart and add its name to the ApplicationSet, and you're done

7. Conclusion

In this article, we looked at Terraform's basic concepts (Provider, Resource, Variable, Module, State) and walked through a hands-on exercise of deploying ArgoCD to a Kind cluster.

Key takeaways:

• Terraform: A declarative IaC tool. Define infrastructure with .tf files and apply it via plan → apply
• State: The core mechanism by which Terraform tracks the current infrastructure state
• Module: Separates resources into reusable units to structure the code
• Real-world structure: Separating roles with the combination of Terraform (cluster) + ArgoCD (deployment automation) + Helm (app configuration) makes management much easier

References

• Terraform Official Documentation
• Terraform Registry - Provider List
• Kind Provider Documentation
• ArgoCD Official Documentation
• Full Source Code - GitHub

1.1 What Is Profiling?

Profiling is a technique for measuring and analyzing resource usage patterns — CPU, memory, I/O, and so on — while a program runs. Through profiling, you can accurately identify performance bottlenecks and find the code regions that need optimization.

Without profiling, if you rely on a gut feeling that "it seems slow," you'll waste time optimizing code unrelated to the actual bottleneck. "Don't optimize without measuring" is a fundamental principle of software performance analysis.

1.2 Why Profiling Matters in Go

Go has runtime-specific concurrency mechanisms such as goroutines, the garbage collector (GC), and channels. These characteristics are powerful, but they can also make it hard to pinpoint the cause of performance problems.

• Goroutine leaks: goroutines that never terminate keep piling up and consume memory
• GC overhead: GC load caused by excessive heap allocation
• Mutex contention: multiple goroutines competing over the same lock, degrading performance
• Channel blocking: goroutine stalls caused by waiting on channels

Go has profiling tools to diagnose these problems built into the standard library, so you can use them right away without any extra installation.

1.3 Introducing the pprof Tools

In Go, profiling is provided mainly through two packages.

net/http/pprof uses runtime/pprof internally, and by registering HTTP handlers it lets you connect remotely to a running program to collect profile data. Its overhead is low enough to use safely even in production environments.

2. pprof Basic Setup

2.1 net/http/pprof - HTTP Endpoint Approach

The simplest method is to import the net/http/pprof package. A single blank import (_) line automatically registers the profiling HTTP endpoints.

package main

import (
	"fmt"
	"log"
	"net/http"
	"sync"
	"time"

	_ "net/http/pprof" // automatically register pprof endpoints
)

func main() {
	// start the HTTP server for pprof
	go func() {
		log.Println(http.ListenAndServe("localhost:6060", nil))
	}()

	fmt.Println("hello world")
	var wg sync.WaitGroup
	wg.Add(1)
	go leakyFunction(wg)
	wg.Wait()
}

// leakyFunction keeps appending strings to a slice, causing a memory leak.
// As append() repeats, the slice's internal array is reallocated again and again,
// and the previous arrays become GC candidates, but new allocations grow faster, so memory usage keeps increasing.
func leakyFunction(wg sync.WaitGroup) {
	defer wg.Done()
	s := make([]string, 3)
	for i := 0; i < 10000000; i++ {
		s = append(s, "magical pandas") // the slice grows without bound, causing a memory leak
		if (i % 100000) == 0 {
			time.Sleep(500 * time.Millisecond)
		}
	}
}

After running the program, if you open http://localhost:6060/debug/pprof/ in a browser, you can see a profile list like the one below.

2.2 runtime/pprof - File Output Approach

In a CLI program or batch job that has no HTTP server, you can use the runtime/pprof package to save profile data directly to a file.

2.2.1 Saving a CPU Profile File

package main

import (
	"log"
	"os"
	"runtime/pprof"
)

func main() {
	// create the CPU profile file
	f, err := os.Create("cpu.prof")
	if err != nil {
		log.Fatal(err)
	}
	defer f.Close()

	// start CPU profiling
	if err := pprof.StartCPUProfile(f); err != nil {
		log.Fatal(err)
	}
	defer pprof.StopCPUProfile()

	// run the code to be profiled
	heavyComputation()
}

func heavyComputation() {
	result := 0
	for i := 0; i < 100000000; i++ {
		result += i * i
	}
}

2.2.2 Saving a Heap Memory Profile File

func writeHeapProfile() {
	f, err := os.Create("mem.prof")
	if err != nil {
		log.Fatal(err)
	}
	defer f.Close()

	// save the heap profile
	if err := pprof.WriteHeapProfile(f); err != nil {
		log.Fatal(err)
	}
}

The saved profile files are analyzed with the go tool pprof command.

# analyze the CPU profile
go tool pprof cpu.prof

# analyze the memory profile
go tool pprof mem.prof

2.3 Using with go test -bench

You can collect profile data while running benchmark tests at the same time. This is useful when analyzing the performance of a specific function.

# collect a CPU profile
go test -bench=. -cpuprofile=cpu.prof

# collect a memory profile
go test -bench=. -memprofile=mem.prof

# collect a blocking profile
go test -bench=. -blockprofile=block.prof

# collect a mutex profile
go test -bench=. -mutexprofile=mutex.prof

The way to analyze the collected profile files is the same.

# analyze the benchmark CPU profile
go tool pprof cpu.prof

# open in the web UI
go tool pprof -http=:8080 cpu.prof

3. Analysis by Profile Type

Go pprof provides various types of profiles. This chapter looks at the characteristics of each profile type, how to collect it, and concrete examples.

The comprehensive example program below is structured so that all types of profiles can be collected simultaneously.

package main

import (
	"log"
	"net/http"
	_ "net/http/pprof"
	"os"
	"os/signal"
	"runtime"
	"syscall"

	"example.com/profiling/pkg/block"
	"example.com/profiling/pkg/cpu"
	"example.com/profiling/pkg/memory"
	"example.com/profiling/pkg/mutex"
	"example.com/profiling/pkg/threadcreate"
)

func main() {
	// start the pprof HTTP server
	go func() {
		log.Println(http.ListenAndServe("localhost:6060", nil))
	}()

	// blocking/mutex profiles are disabled by default, so they must be explicitly enabled
	runtime.SetBlockProfileRate(1)     // record all blocking events (1 = nanosecond threshold)
	runtime.SetMutexProfileFraction(1) // record all mutex contention (1 = sample with probability 1/1)

	// start goroutines that generate load for each type
	go cpu.IncreaseInt()                  // CPU load (infinite loop computation)
	go cpu.IncreaseIntGoroutine()         // CPU load (nested goroutine)
	go memory.AllocMemory()               // heap memory allocation
	go block.PrintHello()                 // stdout blocking (I/O lock contention)
	go block.PrintWorld()                 // stdout blocking (I/O lock contention)
	go threadcreate.CreateGoroutine1000() // mass goroutine creation → triggers OS thread creation
	go mutex.Mutex01()                    // mutex contention
	go mutex.Mutex02()                    // mutex contention
	go mutex.Mutex03()                    // mutex contention

	// wait for a termination signal
	log.Println("profiling server started: http://localhost:6060/debug/pprof/")
	termSignal := make(chan os.Signal, 1)
	signal.Notify(termSignal, syscall.SIGTERM, syscall.SIGINT)
	<-termSignal
}

3.1 CPU Profile

A CPU profile identifies the functions that consume the most CPU time in a program. By default it samples 100 times per second, recording the stack trace of the function running at that moment.

How to Collect

# collect a CPU profile for 30 seconds
go tool pprof http://localhost:6060/debug/pprof/profile?seconds=30

# collect for 10 seconds
go tool pprof http://localhost:6060/debug/pprof/profile?seconds=10

CPU Load Example Code

package cpu

func IncreaseInt() {
	i := 0
	for {
		i = increase1000(i)
		i = increase2000(i)
	}
}

func IncreaseIntGoroutine() {
	go func() {
		i := 0
		for {
			i = increase1000(i)
			i = increase2000(i)
		}
	}()
}

func increase1000(n int) int {
	for n := 0; n < 1000; n++ {
		n = n + 1
	}
	return n
}

func increase2000(n int) int {
	for n := 0; n < 2000; n++ {
		n = n + 1
	}
	return n
}

Example Analysis Result

(pprof) top10
Showing nodes accounting for 5.20s, 98.11% of 5.30s total
Showing top 10 nodes out of 23
      flat  flat%   sum%        cum   cum%
     2.08s 39.25% 39.25%      2.08s 39.25%  main.increase2000
     1.52s 28.68% 67.92%      1.52s 28.68%  main.increase1000
     0.80s 15.09% 83.02%      3.60s 67.92%  main.IncreaseInt
     0.60s 11.32% 94.34%      2.12s 40.00%  main.IncreaseIntGoroutine
     ...

You can see that the increase2000 function accounts for about 39% of CPU time, and increase1000 accounts for about 29%. The difference in loop iteration count (1000 vs 2000) is directly reflected in the CPU time.

3.2 Heap Memory Profile (heap)

A heap profile shows the current memory allocation state. It is used to find memory leaks or to identify functions that use a lot of memory.

How to Collect

# collect a heap profile
go tool pprof http://localhost:6060/debug/pprof/heap

Memory Allocation Example Code

package memory

import "time"

func AllocMemory() {
	bytes1000 := alloc1000()
	bytes1000[0] = '0'

	for {
		time.Sleep(1 * time.Second)
	}
}

func alloc1000() []byte {
	return make([]byte, 1000)
}

inuse_space vs alloc_space

A heap profile can be analyzed from two perspectives.

# based on memory currently in use (default)
go tool pprof -inuse_space http://localhost:6060/debug/pprof/heap

# based on total allocated memory
go tool pprof -alloc_space http://localhost:6060/debug/pprof/heap

inuse_space shows memory that has not been freed by GC and remains in use, so it is mainly used to detect memory leaks. alloc_space includes already-freed memory as well, so it is useful for finding code that allocates frequently.

Comparing Heap Profiles (diff)

Comparing heap profiles from two points in time makes a memory leak even clearer.

# collect the base profile
curl -o base.prof http://localhost:6060/debug/pprof/heap

# collect a second profile a little later
curl -o current.prof http://localhost:6060/debug/pprof/heap

# compare the two profiles
go tool pprof -base=base.prof current.prof

3.3 Goroutine Profile (goroutine)

A goroutine profile shows the stack traces of all currently running goroutines. It is used to detect goroutine leaks or to check which goroutine is blocked where.

How to Collect

# collect a goroutine profile
go tool pprof http://localhost:6060/debug/pprof/goroutine

# full stack dump (view in browser)
curl http://localhost:6060/debug/pprof/goroutine?debug=2

Using the debug=2 parameter, you can view the full stack traces of all goroutines in text form, making it easy to see at a glance where each goroutine is waiting.

Goroutine Leak Example Code

A goroutine leak is the phenomenon where created goroutines never terminate and keep piling up.

package main

import (
	"fmt"
	"log"
	"net/http"
	"time"

	_ "net/http/pprof"
)

func main() {
	go func() {
		log.Println(http.ListenAndServe("localhost:6060", nil))
	}()

	// goroutine leak: waiting on a channel that is never closed
	for i := 0; i < 100; i++ {
		go leakyGoroutine(i)
	}

	// the main goroutine keeps running
	select {}
}

func leakyGoroutine(id int) {
	ch := make(chan struct{}) // a channel nobody closes
	<-ch                     // waits forever -> goroutine leak!
	fmt.Println("never reached", id)
}

In the code above, leakyGoroutine waits on a channel that nobody closes, so 100 goroutines never terminate and keep occupying memory.

Goroutine Leak Prevention Pattern

func safeGoroutine(ctx context.Context, id int) {
	ch := make(chan struct{})
	select {
	case <-ch:
		fmt.Println("received", id)
	case <-ctx.Done():
		fmt.Println("cancelled", id)
		return // terminate normally when context is canceled
	}
}

Using context.Context, you can cancel a goroutine from the outside, which prevents leaks.

3.4 Blocking Profile (block)

A blocking profile analyzes the time goroutines spend in a blocking state. It includes channel receive waits, mutex lock waits, I/O waits, and so on.

How to Enable and Collect

The blocking profile is disabled by default, so it must be explicitly enabled.

// enable the blocking profile (at program startup)
runtime.SetBlockProfileRate(1) // 1 = record all blocking events

The argument to SetBlockProfileRate is a threshold in nanoseconds. Setting it to 1 records all blocking events; larger values ignore short blocking. In production, set an appropriate value to reduce overhead.

# collect the blocking profile
go tool pprof http://localhost:6060/debug/pprof/block

Blocking Example Code

package block

import "fmt"

func PrintHello() {
	for {
		fmt.Printf("Hello\n")
	}
}

func PrintWorld() {
	for {
		fmt.Printf("World\n")
	}
}

fmt.Printf internally acquires a lock on stdout, so when PrintHello and PrintWorld run simultaneously, blocking occurs over the stdout lock.

3.5 Mutex Profile (mutex)

A mutex profile analyzes mutex contention. When multiple goroutines compete over the same mutex, it measures the time each goroutine waited to acquire the lock.

How to Enable and Collect

// enable the mutex profile
runtime.SetMutexProfileFraction(1) // 1 = record all mutex contention

The argument to SetMutexProfileFraction is the sampling rate. 1 records all contention events; N records with probability 1/N.

# collect the mutex profile
go tool pprof http://localhost:6060/debug/pprof/mutex

Mutex Contention Example Code

package mutex

import (
	"fmt"
	"sync"
)

var mu = sync.Mutex{}

func Mutex01() {
	for {
		mu.Lock()
		fmt.Printf("Mutex01\n")
		mu.Unlock()
	}
}

func Mutex02() {
	for {
		mu.Lock()
		fmt.Printf("Mutex02\n")
		mu.Unlock()
	}
}

func Mutex03() {
	for {
		mu.Lock()
		fmt.Printf("Mutex03\n")
		mu.Unlock()
	}
}

Three goroutines compete over the same mu mutex, so the mutex profile records the wait time of each function.

3.6 Thread Creation Profile (threadcreate)

A thread creation profile shows the pattern of OS threads the program created. Excessive thread creation wastes system resources, so this is used to monitor it.

Mass Goroutine Creation Example Code

The Go runtime multiplexes goroutines on top of OS threads to run them. When a goroutine blocks on a system call and the like, the runtime creates a new OS thread so that other goroutines can keep running. Running a large number of goroutines simultaneously lets you observe this thread creation pattern in the profile.

package threadcreate

// CreateGoroutine1000 creates 100,000 goroutines to simulate massive concurrent execution.
// Since the number of goroutines is far greater than GOMAXPROCS, scheduling overhead occurs.
func CreateGoroutine1000() {
	for i := 0; i < 100000; i++ {
		go innerFunc()
	}
}

func innerFunc() {
	n := 0
	for i := 0; i < 1000000; i++ {
		n++
	}
}

# collect the thread creation profile
go tool pprof http://localhost:6060/debug/pprof/threadcreate

4. Using the pprof Analysis Tools

Once you've collected profile data, you now need to use the analysis tools to find the cause of the performance problem. Go provides a powerful CLI tool and web-based visualization tools.

4.1 go tool pprof CLI Interactive Mode

Running go tool pprof enters an interactive shell.

go tool pprof http://localhost:6060/debug/pprof/profile?seconds=10

When collection finishes, a (pprof) prompt appears, and you can analyze the profile data with various commands.

Key Commands

The top Command

(pprof) top10
Showing nodes accounting for 5.20s, 98.11% of 5.30s total
      flat  flat%   sum%        cum   cum%
     2.08s 39.25% 39.25%      2.08s 39.25%  main.increase2000
     1.52s 28.68% 67.92%      1.52s 28.68%  main.increase1000
     0.80s 15.09% 83.02%      3.60s 67.92%  main.IncreaseInt

The Difference Between flat and cum

These are the two most important metrics in profile analysis.

• flat: the time the function spent directly itself (excluding calls to lower-level functions)
• cum (cumulative): the time including the function + all the lower-level functions it called

Example:
func A() {        // flat=1s, cum=3s
    doWork(1s)    // 1 second spent in A itself
    B()           // 2 seconds spent calling B
}

func B() {        // flat=2s, cum=2s
    doWork(2s)    // 2 seconds spent in B itself
}

• Function A: flat=1s (its own work), cum=3s (own 1s + B call 2s)
• Function B: flat=2s (its own work), cum=2s (no lower-level calls)

A function with high flat is a direct optimization target, while a function with high cum requires examining the entire call chain.

The list Command

You can view the source code of a specific function line by line, along with profile information.

(pprof) list increase2000
Total: 5.30s
ROUTINE ======================== main.increase2000
     2.08s      2.08s (flat, cum) 39.25% of Total
         .          .     27: func increase2000(n int) int {
     2.08s      2.08s     28:     for n := 0; n < 2000; n++ {
         .          .     29:         n = n + 1
         .          .     30:     }
         .          .     31:     return n
         .          .     32: }

You can pinpoint that most of the CPU time is spent in the for loop on line 28.

4.2 Web UI Visualization

Using the -http flag with go tool pprof, you can open a browser-based interactive analysis tool.

# open a profile file in the web UI
go tool pprof -http=:8080 cpu.prof

# open the web UI directly from an HTTP endpoint
go tool pprof -http=:8080 http://localhost:6060/debug/pprof/profile?seconds=10

The web UI provides the following views.

Graph View

Visualizes the call graph. Nodes (rectangles) represent functions, and the size and color of a node are proportional to its resource consumption. Arrows represent call relationships, and the thickness of an arrow is proportional to call frequency.

• Large node → a function that consumes a lot of resources
• Thick arrow → a frequent call path
• Red → high resource consumption

Flame Graph

You can view the flame graph in the Flame Graph view. A flame graph visually represents the call stack, letting you grasp performance bottlenecks intuitively.

Top View

Shows the same information as the CLI top command, in table form. You can change the sort criterion or filter.

Source View

Shows profiling results per source line. It's similar to the CLI list command, but you can navigate the entire source file.

4.3 How to Read a Flame Graph

A flame graph is the most intuitive visualization tool in performance analysis.

┌──────────────────────────────────────────────────────┐
│                     main.main                        │ ← root (program entry point)
├────────────────────────┬─────────────────────────────┤
│    main.IncreaseInt    │  main.IncreaseIntGoroutine  │ ← lower-level functions
├───────────┬────────────┼──────────┬──────────────────┤
│increase1000│increase2000│increase1000│  increase2000  │ ← leaf functions
└───────────┴────────────┴──────────┴──────────────────┘

• X-axis: proportion of samples (the wider, the more time spent in that function)
• Y-axis: call stack depth (root at the bottom, leaf at the top)
• Wide block: a lot of time spent in that function (and its lower-level functions)
• Color: usually random and just for distinction (red does not mean a problem)

Analysis point: in a flame graph, find the widest "plateau." A function with a wide plateau is a candidate for a performance bottleneck.

5. Hands-On Example: A Performance Problem Diagnosis Workflow

Let's look step by step at the process of diagnosing a real performance problem.

5.1 Scenario: Diagnosing a CPU Bottleneck

The Problem

A particular API response of a web server is slow. We need to find the cause.

Diagnosis Steps

Step 1: Collect a CPU profile

# collect a CPU profile for 30 seconds
go tool pprof http://localhost:6060/debug/pprof/profile?seconds=30

Step 2: Check hot spots with top

(pprof) top10
Showing nodes accounting for 5.20s, 98.11% of 5.30s total
      flat  flat%   sum%        cum   cum%
     2.08s 39.25% 39.25%      2.08s 39.25%  main.increase2000
     1.52s 28.68% 67.92%      1.52s 28.68%  main.increase1000

→ the increase2000 function accounts for 39% of CPU time

Step 3: Per-line analysis with list

(pprof) list increase2000

→ confirm that the for loop is the bottleneck

Step 4: Check the call graph with web

(pprof) web

→ visually check the call chain to figure out which path calls the function

Verification After Optimization

After optimization, run the same profiling to measure the improvement.

# compare the profiles before and after optimization
go tool pprof -base=before.prof after.prof

5.2 Scenario: Diagnosing a Memory Leak

The Problem

While the service runs in production, memory usage keeps increasing over time.

Diagnosis Steps

Step 1: Collect heap profiles from two points in time

# point 1: right after service start
curl -o heap_t1.prof http://localhost:6060/debug/pprof/heap

# point 2: after some time has passed
curl -o heap_t2.prof http://localhost:6060/debug/pprof/heap

Step 2: Compare the two profiles

# check the memory that increased in t2 relative to t1
go tool pprof -base=heap_t1.prof heap_t2.prof

Step 3: Identify the leak point with inuse_space

(pprof) top10 -inuse_space

→ find the function that allocates memory that is never freed over time

Step 4: Check and fix the source code

(pprof) list leakyFunction

→ identify and fix patterns such as a slice being appended without bound

5.3 Scenario: Diagnosing a Goroutine Leak

The Problem

The number of goroutines keeps increasing over time.

Diagnosis Steps

Step 1: Check the current goroutine count

# check the goroutine count
curl http://localhost:6060/debug/pprof/goroutine?debug=1 | head -1

Step 2: Check goroutine stack traces

# full goroutine stack dump
curl http://localhost:6060/debug/pprof/goroutine?debug=2

Step 3: Identify goroutines waiting at the same location

goroutine 18 [chan receive]:
main.leakyGoroutine(0x0)
    /app/main.go:25 +0x34
...

goroutine 19 [chan receive]:
main.leakyGoroutine(0x1)
    /app/main.go:25 +0x34

→ if many goroutines are found waiting on a channel receive at the same location (main.go:25), suspect a leak

Step 4: Manage the goroutine lifecycle with context.Context

// before: goroutine leak
go func() {
    <-ch // waits forever
}()

// after: cancelable with context
go func(ctx context.Context) {
    select {
    case <-ch:
        // normal processing
    case <-ctx.Done():
        return // normal termination
    }
}(ctx)

6. Integrating pprof with the Echo Framework

To use pprof in a production web server, you need to know how to integrate it with your framework. When using the Echo framework, you can use the echo-pprof library.

package main

import (
	"fmt"
	"net/http"
	"time"

	"github.com/labstack/echo/v4"
	echopprof "github.com/sevenNt/echo-pprof"
)

func main() {
	e := echo.New()
	echopprof.Wrap(e) // register pprof endpoints

	e.GET("/hello", helloHandler)
	e.POST("/stress/cpu", cpuHandler)
	e.POST("/stress/memory", memoryHandler)

	e.Logger.Fatal(e.Start(":8080"))
}

func helloHandler(ctx echo.Context) error {
	return ctx.JSON(http.StatusOK, map[string]string{
		"message": "Hello World",
	})
}

A single echopprof.Wrap(e) line registers pprof endpoints on the Echo server, accessible at http://localhost:8080/debug/pprof/.

Security Considerations in Production

The pprof endpoints expose the internal state of the program, so in production environments you should separate them onto a dedicated port and block external access.

func main() {
	// main server (publicly exposed)
	e := echo.New()
	e.GET("/api/hello", helloHandler)
	go e.Start(":8080")

	// pprof server (internal only, separate port)
	pprofMux := http.NewServeMux()
	pprofMux.HandleFunc("/debug/pprof/", http.DefaultServeMux.ServeHTTP)
	go http.ListenAndServe("localhost:6060", nil) // bind to localhost only
}

7. Useful Auxiliary Tools

7.1 gops

gops is a tool for monitoring running Go processes.

# install gops
go install github.com/google/gops@latest

Add the gops agent to your program.

import "github.com/google/gops/agent"

func main() {
	if err := agent.Listen(agent.Options{}); err != nil {
		log.Fatal(err)
	}
	// ...
}

You can query process information with gops.

# list running Go processes
gops

# query information about a specific process
gops <pid>

# check GC stats
gops gc <pid>

# memory stats
gops memstats <pid>

# current stack trace
gops stack <pid>

# collect a pprof CPU profile
gops pprof-cpu <pid>

# collect a pprof heap profile
gops pprof-heap <pid>

7.2 go tool trace

go tool trace is a tool that traces a program's execution flow along a time axis. If pprof focuses on "where time was spent," trace focuses on "what happened in chronological order."

Collecting Trace Data

# collect a trace for 5 seconds from an HTTP endpoint
curl -o trace.out http://localhost:6060/debug/pprof/trace?seconds=5

# open the trace viewer
go tool trace trace.out

Collecting a Trace in Code

Basic trace collection can be implemented simply with trace.Start and trace.Stop.

package main

import (
	"os"
	"runtime/trace"
)

func main() {
	f, _ := os.Create("trace.out")
	defer f.Close()

	trace.Start(f)
	defer trace.Stop()

	// program code...
}

Per-Section Tracing with Task and Region

Using trace.NewTask and trace.WithRegion, you can logically separate specific work sections in the trace viewer. This is useful in complex programs for figuring out which work spends time in which section.

func worker(ctx context.Context, id int) {
	// Task: defines a logical unit of work (grouped and displayed in the trace viewer)
	ctx, task := trace.NewTask(ctx, fmt.Sprintf("worker-%d", id))
	defer task.End()

	// Region: defines a detailed section within a Task
	trace.WithRegion(ctx, "compute", func() {
		// CPU computation work...
	})

	trace.WithRegion(ctx, "channel-work", func() {
		// channel communication work...
	})

	// Log: records a user-defined log into the trace
	trace.Log(ctx, "status", fmt.Sprintf("worker-%d completed", id))
}

Information You Can See in the Trace Viewer

• Goroutine analysis: distribution of execution/wait time per goroutine
• Network/Sync blocking: network and synchronization blocking events
• Syscall blocking: system call blocking
• Scheduler latency: scheduler delay time
• GC events: garbage collection event timeline

7.3 benchstat

benchstat is a tool that statistically compares Go benchmark results.

# install benchstat
go install golang.org/x/perf/cmd/benchstat@latest

# run benchmarks before optimization (10 repetitions)
go test -bench=. -count=10 > old.txt

# perform code optimization...

# run benchmarks after optimization (10 repetitions)
go test -bench=. -count=10 > new.txt

# compare the results
benchstat old.txt new.txt

Example output:

name          old time/op  new time/op  delta
Increase-8    1.23µs ± 2%  0.45µs ± 1%  -63.41% (p=0.000 n=10+10)

You can check the performance improvement ratio in the delta column. If the p value is below 0.05, the difference is statistically significant.

8. Tips for Using pprof in Production

8.1 Overhead

Importing net/http/pprof itself has no performance impact. Overhead occurs only when you actually collect profile data.

8.2 Security

• Separate the pprof endpoints onto a dedicated port and block external access
• Bind only to localhost to allow local access only
• Add authentication middleware if needed
• In Kubernetes environments, access via port-forward

# access pprof in Kubernetes
kubectl port-forward pod/my-app-xxx 6060:6060

# profile locally
go tool pprof http://localhost:6060/debug/pprof/heap

8.3 Continuous Profiling

To catch intermittent performance problems in production, you need a tool that continuously collects profiles.

• Pyroscope: an open-source continuous profiling platform
• Google Cloud Profiler: a GCP-based profiling service
• Datadog Continuous Profiler: integrated with monitoring tools

These tools periodically collect profiles in the background and store them as time-series data, letting you compare and analyze the performance state at past points in time.

9. Summary

Use Scenarios by Profile Type

Diagnosis Workflow Summary

flowchart TD
    A["Performance problem detected"] --> B{"Classify symptom"}
    B -->|"High CPU usage"| C["Collect CPU Profile"]
    B -->|"Memory increase"| D["Collect Heap Profile"]
    B -->|"Goroutine increase"| E["Collect Goroutine Profile"]
    B -->|"Throughput degradation"| F["Collect Mutex/Block Profile"]
    C --> G["Analyze with top, list, web"]
    D --> H["inuse_space + diff comparison"]
    E --> I["Check stack dump with debug=2"]
    F --> J["Check contention/wait points"]
    G --> K["Optimize the bottleneck function"]
    H --> K
    I --> K
    J --> K
    K --> L["Verify by re-collecting the profile"]

The code written in this post is available on github.

10. References

• https://pkg.go.dev/net/http/pprof
• https://pkg.go.dev/runtime/pprof
• https://go.dev/blog/pprof
• https://go.dev/doc/diagnostics
• https://github.com/google/pprof
• https://github.com/google/gops
• https://jvns.ca/blog/2017/09/24/profiling-go-with-pprof/
• https://www.practical-go-lessons.com/chap-36-program-profiling

1. select Statement Basics

select is similar to switch but specialized for channel operations. It runs one of the cases that is ready.

select {
case msg := <-ch1: // runs if data arrives from ch1 first
    fmt.Println("ch1:", msg)
case msg := <-ch2: // runs if data arrives from ch2 first
    fmt.Println("ch2:", msg)
}

1.1 Random Selection Characteristic

When multiple cases are ready at the same time, the Go runtime picks one at random. This prevents the starvation problem where a particular channel is always prioritized.

func TestSelectMultipleReady(t *testing.T) {
    ch1 := make(chan int, 1) // channel with buffer 1
    ch2 := make(chan int, 1)

    ch1Count, ch2Count := 0, 0
    for range 1000 { // repeat 1000 times to check the selection ratio
        ch1 <- 1 // put values into both channels at once so both are ready
        ch2 <- 2

        select {
        case <-ch1: // both cases are ready, so the runtime picks at random
            ch1Count++
        case <-ch2:
            ch2Count++
        }
        // drain the remaining value from the channel that wasn't selected
        select {
        case <-ch1:
        case <-ch2:
        default:
        }
    }

    t.Logf("ch1: %d, ch2: %d", ch1Count, ch2Count)
    // example output: ch1: 516, ch2: 484 (roughly 50:50)
}

2. Using the default Case

Adding a default case makes it non-blocking. When no channel is ready, default runs immediately.

2.1 Non-blocking Receive

select {
case val := <-ch:
    fmt.Println("received:", val)
default:
    fmt.Println("no data available") // runs immediately if the channel is empty
}

2.2 Non-blocking Send

ch := make(chan int, 1)
ch <- 1 // buffer full

select {
case ch <- 2:
    fmt.Println("sent")
default:
    fmt.Println("buffer full") // runs immediately if the buffer is full
}

default is useful for polling or busy-wait, but overusing it in a loop can use excessive CPU.

3. Handling Timeouts

3.1 time.After

time.After returns a channel that sends a value after the specified duration. Combined with select, you can implement a timeout simply.

func TestTimeoutWithTimeAfter(t *testing.T) {
    ch := make(chan string)

    go func() {
        time.Sleep(200 * time.Millisecond) // simulate a slow task taking 200ms
        ch <- "result"
    }()

    select {
    case msg := <-ch: // handle normally if the task result arrives first
        t.Log("received:", msg)
    case <-time.After(50 * time.Millisecond): // receive from the timeout channel if 50ms is exceeded
        t.Log("timeout!")
    }
}

3.2 context.WithTimeout

In practice, context.WithTimeout is used more often. context allows cancellation propagation and lets you manage a timeout across multiple goroutines.

// simulateAPICall - simulates an API call with a context-based timeout
func simulateAPICall(ctx context.Context, delay time.Duration) (string, error) {
    ch := make(chan string, 1) // buffer 1: the goroutine can send the result and terminate right away

    go func() {
        time.Sleep(delay) // simulate API call latency
        ch <- "api response"
    }()

    select {
    case result := <-ch: // return normally if the API response arrives first
        return result, nil
    case <-ctx.Done(): // return an error if the context timeout is exceeded
        return "", ctx.Err() // context.DeadlineExceeded
    }
}

func TestSimulateAPICallTimeout(t *testing.T) {
    // set a 50ms timeout — the API takes 200ms, so a timeout occurs
    ctx, cancel := context.WithTimeout(context.Background(), 50*time.Millisecond)
    defer cancel() // always call cancel to release resources

    result, err := simulateAPICall(ctx, 200*time.Millisecond)
    assert.ErrorIs(t, err, context.DeadlineExceeded)
    assert.Empty(t, result)
}

4. Fan-in / Fan-out Patterns

4.1 Fan-out

A pattern that distributes a single input to multiple workers. Multiple goroutines take work from the same channel.

graph LR
    J[jobs] --> W1[Worker 1] --> R1[result]
    J --> W2[Worker 2] --> R2[result]
    J --> W3[Worker 3] --> R3[result]

func TestFanOut(t *testing.T) {
    jobs := make(chan int, 10)  // shared channel for distributing work
    numWorkers := 3

    workerResults := make([]chan int, numWorkers) // result channel per worker
    for i := range numWorkers {
        workerResults[i] = make(chan int, 10)
    }

    var wg sync.WaitGroup
    for i := range numWorkers {
        wg.Add(1)
        go func() { // each worker takes work from the same jobs channel
            defer wg.Done()
            for job := range jobs { // the loop ends when jobs is closed
                workerResults[i] <- job * job // square and send the result
            }
            close(workerResults[i])
        }()
    }

    for i := 1; i <= 9; i++ { // send 9 jobs to the channel
        jobs <- i
    }
    close(jobs) // all jobs sent → workers end their loop
    wg.Wait()
}

4.2 Fan-in

A pattern that merges the results of multiple channels into a single channel.

graph LR
    S1[source1] --> M[merged channel]
    S2[source2] --> M
    S3[source3] --> M

// fanIn - merges values from multiple channels into a single channel
func fanIn(channels ...<-chan string) <-chan string {
    var wg sync.WaitGroup
    merged := make(chan string) // the single channel where all results collect

    for _, ch := range channels {
        wg.Add(1)
        go func() { // a goroutine per source channel forwards values to merged
            defer wg.Done()
            for v := range ch { // the loop ends when the source channel is closed
                merged <- v
            }
        }()
    }

    go func() {
        wg.Wait()   // wait until all sources complete
        close(merged) // close the merged channel after all sources complete
    }()

    return merged
}

Example of calling fanIn:

func TestFanIn(t *testing.T) {
    // 3 independent data sources
    source1 := make(chan string, 3)
    source2 := make(chan string, 3)

    go func() {
        for _, s := range []string{"a1", "a2", "a3"} {
            source1 <- s
        }
        close(source1) // always close after sending data
    }()

    go func() {
        for _, s := range []string{"b1", "b2"} {
            source2 <- s
        }
        close(source2)
    }()

    // Fan-in: merge 2 channels into one
    merged := fanIn(source1, source2)

    for v := range merged { // the loop ends when the merged channel is closed
        fmt.Println(v)
    }
    // output (order is non-deterministic): a1, b1, a2, b2, a3
}

4.3 Combining Fan-out + Fan-in

In practice, you combine the two patterns to build a parallel processing pipeline.

graph LR
    Input --> Fan-out
    Fan-out --> Worker1
    Fan-out --> Worker2
    Fan-out --> Worker3
    Worker1 --> Fan-in
    Worker2 --> Fan-in
    Worker3 --> Fan-in
    Fan-in --> Result

5. The Nil Channel Trick

Characteristics of a nil channel:

• sending to a nil channel blocks forever
• receiving from a nil channel blocks forever
• a nil channel case in a select is ignored

Using this, you can dynamically enable/disable cases in a select.

func TestNilChannelDisable(t *testing.T) {
    ch1 := make(chan int, 3)
    ch2 := make(chan int, 3)

    ch1 <- 1; ch1 <- 2; ch1 <- 3; close(ch1) // send 3 values to ch1 then close
    ch2 <- 10; ch2 <- 20; close(ch2)           // send 2 values to ch2 then close

    var results []int
    // declare as receive-only channel variables — can be disabled by assigning nil
    var active1, active2 = (<-chan int)(ch1), (<-chan int)(ch2)

    for active1 != nil || active2 != nil { // when both become nil, all data is consumed
        select {
        case v, ok := <-active1:
            if !ok {
                active1 = nil // closed channel → setting to nil makes select ignore it
                continue
            }
            results = append(results, v)
        case v, ok := <-active2:
            if !ok {
                active2 = nil // disable ch2 the same way
                continue
            }
            results = append(results, v)
        }
    }

    assert.Len(t, results, 5) // ch1: 3 + ch2: 2 = 5 total
}

Use cases:

• when merging multiple data sources, disable each source as it completes
• turn processing of a particular channel on/off depending on a condition

6. Wrapping Up

In the next part, we'll cover the sync package, which safely manages shared resources between goroutines.

7. References

• Go Tour - Select
• Go Blog - Pipelines and cancellation

Claude Code is an AI-powered CLI tool built by Anthropic that reads and modifies code directly in the terminal and performs a wide range of development tasks. It goes beyond simple question-and-answer interactions to autonomously handle file exploration, code modification, Git operations, and test execution—an agentic coding tool.

Using Claude Code with its default configuration is already productive enough, but when repetitive work patterns emerge or you want to apply project-specific rules, you need extensions. Claude Code provides three core mechanisms for this.

These three look similar, but they break problems down in fundamentally different ways. This article organizes the concept, configuration, and practical examples of each, and discusses when to choose which.

The example code used in this article is available in the tutorials-go/.claude repository.

2. Command (Slash Command)

2.1 Concept

A Command is a prompt template that the user runs directly by typing /. It acts as a shortcut that stores a frequently repeated task as a single command and invokes it when needed.

Key characteristics:

• Invoked directly by the user (/commit, /plan-task, etc.)
• One-time execution: the prompt is injected at invocation time and Claude executes it immediately
• Argument passing supported: parameters passed in the form /command arg1 arg2
• Autocomplete support: typing / displays the list of available commands
• Inline execution in the main conversation context (no separate isolation)

2.1.1 Storage Location

~/.claude/commands/        # Global (used across all projects)
.claude/commands/          # Project-specific (used only in that project)

Global commands are used commonly across all projects, while project commands can be stored in the .claude/commands/ directory and shared with teammates via Git.

Using subdirectories creates namespace separation.

.claude/commands/
├── commit.md            # /commit
├── plan-task.md         # /plan-task
├── start-task.md        # /start-task
└── work/                # Namespace (group commands via subdirectory)
    ├── commit-pr.md     # /work:commit-pr
    └── start-task.md    # /work:start-task

2.2 Practical Example: Repetitive Work in a Single Slash

2.2.1 Git Commit Automation (/commit)

This is the most basic form of a Command—a simple prompt template. Instead of repeating git add, git commit, and git push every time you modify code, a single /commit automates everything from analyzing changes to generating the commit message to pushing.

.claude/commands/commit.md:

## Purpose
Commit modified files and push to the remote repository

## Execution Steps
1. Check changes with `git status`
2. If the current branch is main/master:
   - Create a new branch in the format `feature/{summary-of-work}`
3. Stage changed files (`git add`)
4. Write the commit message (conventional commits format)
5. Push to the remote repository

## Rules
- No direct commits to the main/master branch
- Commit message format: `type: brief description`
  - type: feat, fix, docs, refactor, test, chore, etc.

Usage: After modifying code, type /commit and Claude analyzes the changes, automatically generates a conventional commit message, and commits.

2.2.2 Generating Implementation Docs from a PRD (/plan-task)

This is an example of a Command that takes arguments using $ARGUMENTS. Instead of manually creating an implementation document and todo checklist every time after writing a PRD (requirements document), you just pass the PRD path and Claude analyzes it and generates them automatically.

.claude/commands/plan-task.md:

## Purpose
Generate an implementation document and todo checklist based on $ARGUMENTS (requirements file)

## Arguments
- $ARGUMENTS: requirements file path (e.g., docs/start/1_feature_prd.md)

## Execution Steps
1. Read and analyze the requirements file ($ARGUMENTS)
2. Generate the implementation document ({order}_{feature-name}_implementation.md)
   - Include only the core implementation details
   - Exclude unnecessary content such as future plans and extensibility
3. Generate the todo checklist ({order}_{feature-name}_todo.md)
   - Break it into stages
   - Each item in checkbox format (- [ ])

## File Generation Rules
- Create in the same directory as the requirements file
- Filename pattern: `{order}_{feature-name}_{document-type}.md`

## Example
Input: `/plan-task docs/start/1_github_action_prd.md`

Output:
- `docs/start/1_github_action_implementation.md`
- `docs/start/1_github_action_todo.md`

Usage: Typing /plan-task docs/start/3_claude_prd.md analyzes the PRD and automatically generates the implementation document and todo checklist.

Key point: It takes user arguments via $ARGUMENTS and operates dynamically. Although it is a multi-stage workflow of read file -> analyze -> generate file, it still runs inline in the main conversation context.

2.2.3 Starting a Task (/start-task)

This is an example of a composite-workflow Command that combines multiple tools (GitHub MCP, Git). When starting development of a new feature, it handles GitHub Issue creation, feature branch creation, and work environment setup with a single command. It demonstrates how Commands can extend beyond simple prompts to integrate external tools.

.claude/commands/start-task.md:

## Purpose
Start work based on $ARGUMENTS (PRD document)

## Arguments
- $ARGUMENTS: PRD document path (e.g., docs/start/3_claude_prd.md)

## Execution Steps
1. Create a GitHub Issue (using GitHub MCP)
   - title: PRD title
   - body: summary of PRD content
   - assignee: kenshin579
2. Pull the latest code from the master branch
3. Create a new feature branch: `feature/{issue-number}-{feature-name}`
4. If a todo file exists, proceed with the work in order
5. On completion of each step:
   - Commit the changes
   - Mark the item as done in the todo file (- [x])

## Rules
- No direct commits to the master branch
- Follow the step order in the todo file
- Commit messages in conventional commits format

## Example
Input: `/start-task docs/start/3_claude_prd.md`

Behavior:
1. Create GitHub Issue #607: "Claude Code Skills vs Commands vs Subagents blog examples"
2. Create branch `feature/607-claude-blog-examples`
3. Start work in the order of the todo file

Key point: After generating the implementation document and todo with /plan-task, you can kick off the actual work with /start-task—workflow chaining between Commands is possible. This is a composite Command that combines GitHub MCP + Git commands.

3. Skill

3.1 Concept

A Skill is a knowledge package that Claude automatically detects and loads. While the user can invoke it directly, the core feature is that Claude analyzes the current task context and automatically activates the relevant Skill.

Key characteristics:

• Automatically invoked by the model: Claude judges relevance and loads it without the user explicitly running it
• Manual invocation also possible: with user-invocable: true, you can invoke it directly via /skill-name
• Progressive Disclosure: it first scans the metadata (about 100 tokens) and loads the full content (under 5,000 tokens) only when relevant
• Folder-based structure: auxiliary files (templates, references, scripts) can be packaged together
• Tool restriction possible: allowed-tools restricts the tools the Skill can use
• Isolated execution possible: with context: fork, it runs in a separate context (the boundary with Subagents)

3.1.1 Storage Location

~/.claude/skills/          # Global (personal)
.claude/skills/            # Project-specific

Each Skill is organized as an independent folder.

.claude/skills/
├── go-convention/
│   └── SKILL.md
├── go-project-layout/
│   └── SKILL.md
├── api-convention/
│   └── SKILL.md
└── analyze-codebase/
    └── SKILL.md

3.1.2 SKILL.md Frontmatter Fields

Note on the agent field: Built-in types include Explore (code exploration, read-only), Plan (implementation-plan research), and general-purpose (general, default). You can also specify the name of a custom agent defined in .claude/agents/.

3.2 Practical Example: Project Knowledge Injected Automatically

3.2.1 Go Coding Convention (go-convention)

This example demonstrates a Skill's core features: "automatic invocation" and "knowledge injection." When you request "write some Go code," Claude looks at the description and automatically activates the Skill. At that point, the coding rules written in the SKILL.md body are loaded into the main conversation's context as if they were a system prompt—this is "knowledge injection." The injected knowledge persists until the conversation ends, so subsequent code generation or reviews automatically follow the conventions without separate instructions.

.claude/skills/go-convention/SKILL.md:

---
name: go-convention
description: Apply the project's coding conventions when writing or reviewing Go code.
  Used automatically when creating, modifying, or reviewing Go files.
model: haiku
user-invocable: true
allowed-tools: Read, Grep, Glob
---

## This Project's Go Coding Conventions

### Package Structure
- Test files are placed in the same directory as the source file: `*_test.go`
- Mock files are created in the `mocks/` subdirectory
- Each directory is organized as an independent example (may have its own `go.mod`)

### Test Writing Rules
- Use testify: `github.com/stretchr/testify/assert`
- Apply the table-driven test pattern
- Test function name: `Test{FunctionName}_{Scenario}` format

### Error Handling
- For custom error types, use `errors.New()` or `fmt.Errorf("context: %w", err)`
- Define sentinel errors as package-level variables: `var ErrNotFound = errors.New("not found")`

### Import Ordering
- Order: standard library → external packages → internal packages
- Internal package alias: use an underscore prefix (`_articleHttp`)

Behavior scenario:

1. Automatic invocation: When the user requests "create a new Go file," Claude recognizes the "creating, modifying Go files" wording in the description, automatically loads this Skill, and applies the conventions
2. Manual invocation: Invoke /go-convention directly to check whether existing code follows the conventions

Key points:

• The trigger condition in the description is clear, so Claude automatically invokes it as appropriate (the key difference from a Command)
• user-invocable: true also enables manual invocation
• The knowledge is injected into the main conversation and continues to influence later work

3.2.2 Go Project Layout (go-project-layout)

When you use the !`shell command` syntax in the SKILL.md body, the shell command runs at the moment the Skill is activated and its result is inserted into the body. This is called "dynamic context." For example, if you write !`tree project-layout/ -L 3`, the tree command runs each time the Skill loads and injects the actual directory structure into the context. Unlike writing the structure directly as static text, this always reflects the latest state even when the project structure changes.

Any command runnable in a shell can be used, so Python scripts or pipe combinations are also possible.

# Run a Python script
!`python3 scripts/generate_context.py`

# Pipe combination
!`cat config.json | python3 -c "import sys,json; print(json.dumps(json.load(sys.stdin), indent=2))"`

However, since it runs every time the Skill is activated, a long-running script can delay Skill loading.

.claude/skills/go-project-layout/SKILL.md:

---
name: go-project-layout
description: Apply a clean architecture folder structure when creating a new Go project
  or changing its structure.
model: haiku
user-invocable: true
allowed-tools: Read, Grep, Glob
---

## Reference Project Structure

Below is the clean architecture layout used in this project.
Follow this structure when creating a new Go project.

!`tree project-layout/go-clean-arch-v2 -I vendor -L 3`

## Roles by Layer

### `cmd/`
- Application entry point (`main.go`)
- DI container setup, server startup

### `domain/`
- Core business entities (struct)
- Repository/use case interface definitions
- Error type definitions (`errors.go`)
- Mock files located in `domain/mocks/`

### `{domain-name}/` (e.g., `article/`, `author/`)
- `handler.go`: HTTP handlers (Echo routing)
- `usecase.go`: business logic implementation
- `repository.go`: data access implementation
- `*_test.go`: tests for each file

### `pkg/`
- `config/`: Viper-based configuration management
- `database/`: DB connection setup
- `middleware/`: common middleware such as CORS and authentication

## Dependency Direction
\```
cmd/ → {domain}/ → domain/
         ↓
        pkg/
\```
- The domain package has no external dependencies (pure Go)
- Domain-specific packages implement the domain interfaces
- cmd/ is responsible for assembling all packages

Key points:

• With ! (a dynamic-context command), the actual project structure is read via tree at execution time—referencing runtime data rather than static text
• It can be separated from go-convention (coding style) for separation of concerns
• Later combined and used in the api-developer Subagent via skills: [go-project-layout]

3.2.3 Codebase Analysis with context: fork (analyze-codebase)

This example shows that a Skill can run in an isolated context like a Subagent. Because it runs in a separate context via context: fork, it can analyze a large number of files without consuming the main conversation's context window and returns only the result.

.claude/skills/analyze-codebase/SKILL.md:

---
name: analyze-codebase
description: Analyzes and summarizes the structure of a codebase
model: sonnet
user-invocable: true
context: fork
agent: Explore
---

Analyze the codebase at the $ARGUMENTS path.

## Analysis Items
1. **Directory structure**: file and package organization
2. **Core types/interfaces**: list of key structs and interfaces
3. **Dependencies**: dependency relationships between external libraries and internal packages
4. **Test status**: presence of test files, test patterns (testify, testcontainers, etc.)
5. **Entry point**: main.go or the main executable file

## Output Format
Summarize in markdown, referencing each file in `filename:line-number` format

Usage: Running /analyze-codebase golang/concurrency has the Explore agent analyze that directory in a separate context and return only the result to the main conversation.

Key points:

• Using context: fork makes the Skill run isolated in a separate context
• agent: Explore specifies the agent type to use (optimized for fast exploration)
• Reading a large number of files does not pollute the main context window
• The point where the boundaries of Skills and Subagents meet: Skill format + Subagent execution model

3.3 Skill vs CLAUDE.md

Both provide knowledge to Claude, but there is a fundamental difference.

Decision criterion: Putting rules that are always needed in every conversation in CLAUDE.md, and separating specialized knowledge needed only in specific situations into Skill, is how to use context efficiently.

3.4 Improving Automatic Activation

If a Skill does not activate automatically as intended, you can use a Hook to explicitly trigger activation. A Hook registers a regex matcher on the UserPromptSubmit event in .claude/settings.json, so that when the user input matches the pattern, it instructs Claude to use a specific Skill.

Example 1: Force-activate the subagent-creator Skill on requests like "create a subagent"

// .claude/settings.json
{
  "hooks": {
    "UserPromptSubmit": [
      {
        "matcher": "sub-?agent|custom agent|에이전트 만들",
        "command": "echo 'Use Skill(subagent-creator)'"
      }
    ]
  }
}

When the user types "create a subagent" or "create a custom agent," Claude automatically loads the subagent-creator Skill and guides the agent-creation process.

Example 2: Force-activate the go-convention Skill on Go test-related requests

{
  "hooks": {
    "UserPromptSubmit": [
      {
        "matcher": "테스트 작성|test 추가|_test\\.go",
        "command": "echo 'Use Skill(go-convention)'"
      }
    ]
  }
}

When you request "write a test for this function," the go-convention Skill is force-loaded and conventions such as using testify and the table-driven test pattern are applied. This is useful when automatic activation via the description alone does not work well.

4. Subagent

4.1 Concept

A Subagent is a specialized agent with its own independent context window. When the main Claude encounters a complex task, it delegates to an appropriate Subagent, which performs the work in its own context and then returns a summary of the result.

Key characteristics:

• Independent context: does not pollute the main conversation's context
• Role separation: separated by specialized domains such as code review, debugging, and test execution
• Tool restriction: tools/disallowedTools allow only the tools appropriate for the role
• Model selection: a different model can be used depending on task complexity (cost savings)
• Skill combination: domain knowledge is injected via the skills field to strengthen expertise
• Automatic delegation: based on the description, Claude automatically delegates work at the appropriate time

4.1.1 Storage Location

~/.claude/agents/          # Global (personal)
.claude/agents/            # Project-specific

Each Subagent is defined as a single .md file.

.claude/agents/
├── code-reviewer.md       # Code review specialist
├── debugger.md            # Debugging specialist
├── test-runner.md         # Test execution specialist
└── api-developer.md       # API development specialist (Skill integration)

4.1.2 Frontmatter Fields

4.2 Practical Example: Building Role-Specific Specialist Agents

4.2.1 Code Review Specialist (code-reviewer)

This example demonstrates independent execution and read-only tool restriction. It is automatically delegated to right after code is modified to perform a review, but since it has no Write/Edit tools, it cannot change the code directly and returns only feedback.

.claude/agents/code-reviewer.md:

---
name: code-reviewer
description: A professional code review specialist. Proactively reviews code quality,
  security, and maintainability. Use right after writing or modifying code.
tools: Read, Grep, Glob, Bash
model: inherit
---

You are a senior code reviewer who ensures high code quality and security.

When invoked:
1. Run git diff to check recent changes
2. Focus on the modified files
3. Begin the review immediately

Review checklist:
- Is the code simple and readable
- Are functions and variables well named
- Is there duplicated code
- Is there proper error handling
- Are there any exposed secrets or API keys
- Is input validation implemented
- Is there good test coverage
- Are performance considerations addressed

Provide feedback organized by priority:
- Critical issues (must fix)
- Warnings (should fix)
- Suggestions (consider improving)

Include concrete code examples of how to resolve issues.

Behavior scenario:

1. The user writes/modifies code
2. Claude recognizes the "Use right after writing or modifying code" wording in the description
3. Automatically delegates the work to the code-reviewer subagent
4. The Subagent analyzes git diff in a separate context and returns the review result

Key point: tools: Read, Grep, Glob, Bash has no Write/Edit. Being read-only, there is no risk of accidentally modifying code during analysis.

4.2.2 Debugging Specialist (debugger)

Unlike code-reviewer, this is a Subagent example that includes Edit to perform fixes as well. When a test failure or error occurs, it is automatically delegated to, analyzes the cause, and directly modifies the code to resolve the problem.

.claude/agents/debugger.md:

---
name: debugger
description: A debugging specialist for errors, test failures, and unexpected behavior.
  Use proactively when a problem occurs.
tools: Read, Edit, Bash, Grep, Glob
---

You are an expert debugger specializing in root cause analysis.

When invoked:
1. Capture the error message and stack trace
2. Identify reproduction steps
3. Isolate the failure location
4. Implement a minimal fix
5. Verify the fix with `go test`

Debugging process:
- Analyze error messages and logs
- Check recent code changes (git diff, git log)
- Form hypotheses and test them
- Check related test files (*_test.go)

For each issue, provide:
- An explanation of the root cause
- Evidence supporting the diagnosis (filename:line-number)
- A concrete code fix
- Test execution results after the fix

Focus on solving the fundamental problem, not the symptoms.

Key point: With tools: Read, Edit, Bash, Grep, Glob, Edit is added compared to code-reviewer, allowing it to modify code directly. It autonomously performs the entire flow of error analysis -> cause identification -> code modification -> go test verification in a separate context.

4.2.3 Test Execution Specialist (test-runner)

This example demonstrates fine-grained control with disallowedTools and model: haiku. It is responsible only for test execution and result reporting, and is restricted from modifying code. Since it is a lightweight task, the haiku model is specified to optimize cost and speed.

.claude/agents/test-runner.md:

---
name: test-runner
description: A specialist that runs Go tests and analyzes the results. Use for test
  execution requests or when test verification is needed after code changes.
tools: Read, Bash, Grep, Glob
disallowedTools: Write, Edit
model: haiku
---

You are a specialist in running tests and analyzing results for Go projects.

When invoked:
1. Check the test files of the target package (*_test.go)
2. Run `go test` (verbose + coverage)
3. Analyze the results and generate a report

Execution commands:
- Single package: `go test -v -cover ./path/to/package/...`
- Specific test: `go test -v -run TestFunctionName ./path/to/package`
- All: `go test -v -cover ./...`

Report format:
- Total tests / passed / failed / skipped
- Per failed test: test name, error message, failure location (filename:line-number)
- Coverage: coverage % per package
- Execution time

Failure analysis:
- Compare expected vs actual values of failed tests
- Reference related source code (filename:line-number)
- Estimate possible causes (do not modify code)

Do not modify code directly. Provide only the analysis results.

Key points:

• disallowedTools: Write, Edit explicitly forbids code modification (analysis only)
• model: haiku uses a low-cost model for the simple run+analyze task to save costs
• The system prompt also states "Do not modify code directly" as a double safeguard

4.3 Comparing the Tool Combinations of the 3 Subagents

They are the same kind of Subagent, but the scope of what they can do differs completely depending on the tool combination.

4.4 Design Principle: "Subagent Analyzes, Main Claude Executes"

The effective Subagent design pattern is the separation of analysis and execution.

flowchart LR
    A[User request] --> B[Main Claude]
    B -- Delegate --> C(Subagent: analyze)
    C -- Return result --> D(Main Claude: execute)

    style C fill:#e8f4fd,stroke:#1a73e8
    style D fill:#fce8e6,stroke:#d93025

• Subagent (analyze): uses only Read, Grep, Glob → code exploration, problem analysis, planning
• Main Claude (execute): uses Write, Edit, Bash → modifies based on the Subagent's analysis results

Granting the Subagent only read-only tools provides:

• Safety: no accidental file modification during the analysis stage
• Context preservation: large-scale file exploration does not pollute the main conversation
• Result summarization: the Subagent's work result comes back summarized, so only the essentials are conveyed

The importance of conciseness: A Subagent's system prompt performs better the more concise it is. In one experiment, reducing an 803-line agent prompt to 281 lines (a 65% reduction) raised the evaluation score from 62/100 to 82–85/100 with no loss of functionality.

5. Subagent + Skill Integration

5.1 API Development Specialist (api-developer + api-convention + go-project-layout)

This example shows a Subagent preloading Skills to operate as a specialist equipped with domain knowledge.

First is the Skill that serves as the knowledge. With user-invocable: false, direct invocation is blocked, but it can be used from a Subagent.

.claude/skills/api-convention/SKILL.md:

---
name: api-convention
description: RESTful API design conventions
user-invocable: false
---

## API Design Rules

### URL Naming
- Use plural nouns: `/users`, `/articles`
- Hierarchical relationships: `/users/{id}/articles`
- No verbs: `/getUser` → `/users/{id}`

### Response Format
- Success: `{ "data": ..., "meta": { "page": 1, "total": 100 } }`
- Error: `{ "error": { "code": "NOT_FOUND", "message": "..." } }`

### HTTP Status Codes
- 200: success, 201: created, 204: delete success
- 400: bad request, 401: unauthenticated, 403: forbidden, 404: not found
- 500: server error

### Echo Framework Patterns
- Handlers located in the `http/` directory
- Route groups: `e.Group("/api/v1")`
- Middleware: CORS and JWT verification applied at the group level

And here is the executor Subagent that leverages this knowledge.

.claude/agents/api-developer.md:

---
name: api-developer
description: A professional developer who implements API endpoints. Designs and implements
  RESTful APIs based on the Echo framework.
tools: Read, Write, Edit, Bash, Grep, Glob
model: sonnet
skills:
  - api-convention
  - go-project-layout
---

You are an API development specialist based on the Go Echo framework.

When invoked:
1. Define the domain model (struct) of the requested API
2. Design the repository interface
3. Implement the use case (business logic)
4. Write the HTTP handler
5. Register the router
6. Write tests

Project structure (clean architecture):
- `domain/`: entities and interfaces
- `repository/`: data access implementation
- `usecase/`: business logic
- `http/`: handlers and routers

Be sure to follow the rules of the preloaded api-convention and go-project-layout skills.

Behavior scenario:

1. The user requests "add a user CRUD API"
2. Claude delegates to the api-developer subagent
3. When the Subagent starts, it automatically loads the contents of the api-convention and go-project-layout Skills
4. Implements the endpoints while adhering to the API conventions and project structure

Key points:

• skills: [api-convention, go-project-layout] injects domain knowledge into the Subagent
• The Skill's user-invocable: false blocks direct invocation but allows use from a Subagent
• The role split of Skills = knowledge, Subagents = executors is clear

6. When Should You Use Which?

6.1 Decision Tree for Choosing

When you are unsure which of the three extensions to use, following the decision tree below will help you find the right choice.

flowchart TD
    A["Do you repeat this task frequently?"] -- No --> B["Just ask Claude directly"]
    A -- Yes --> C["Is it the same procedure every time?"]
    C -- Yes --> D["Command"]
    D -.- D1["/commit, /start-task, etc."]
    C -- No --> E["Do you want Claude to apply it on its own?"]
    E -- Yes --> F["Skill"]
    F -.- F1["go-convention, go-project-layout, etc."]
    E -- No --> G["Do you need independent analysis/processing?"]
    G -- Yes --> H["Subagent"]
    H -.- H1["code-reviewer, debugger, etc."]
    G -- No --> B

    style D fill:#d4edda,stroke:#28a745
    style D1 fill:#d4edda,stroke:#28a745,stroke-dasharray: 5 5
    style F fill:#e8f4fd,stroke:#1a73e8
    style F1 fill:#e8f4fd,stroke:#1a73e8,stroke-dasharray: 5 5
    style H fill:#fce8e6,stroke:#d93025
    style H1 fill:#fce8e6,stroke:#d93025,stroke-dasharray: 5 5

6.2 Recommendations by Situation

Once the decision tree has given you a rough direction, you can find a recommendation for your specific situation in the table below.

6.3 Comparison Table

This table lets you compare the core differences of the three features at a glance. In particular, advanced features such as tool restriction, model selection, and parallel execution are supported only by Skills and Subagents.

6.4 Practical Tips

Understanding by analogy:

• Commands = macros (run repetitive work as a shortcut)
• Skills = reference documents (spread out on your desk and referenced while working)
• Subagents = teammates (work independently at a separate desk and hand back only the result)

Practical growth path: You do not need to use all three features from the start. Introducing them step by step naturally broadens your range of use.

1. Start with Commands: turn daily repetitive tasks (commits, deployments, PR creation) into slash commands
2. When patterns emerge, move to Skills: package knowledge such as per-project coding rules and review checklists as Skills
3. As things get complex, move to Subagents: separate work requiring independent analysis—like code review, debugging, and document exploration—into Subagents
4. Combine: inject Skills into a Subagent to build a specialist agent equipped with domain knowledge

Watch out for anti-patterns:

• Overusing Subagents: separating even simple tasks into Subagents only increases overhead. If you do not need an independent context, a Command is enough.
• Using a Skill like a macro: a Skill provides "knowledge," not the execution of a "procedure." If sequential execution is the goal, a Command is more appropriate.

7. Summary of Constraints

8. FAQ

Q. Can you also specify model in a Command?

A. No. A Command is a pure markdown prompt template without frontmatter, so it does not support metadata settings such as model. When a Command runs, the model used in the current conversation is applied as is. To specify a model, you must use a Skill (model field) or a Subagent (model field).

Q. Can you call another Subagent from within a Subagent?

A. No. Subagent nesting is not supported. If you need a complex pipeline, you must design it so that the main Claude calls multiple Subagents sequentially or in parallel.

Q. Can you use a Skill and a Command at the same time?

A. Yes. For example, while running the /commit Command, the go-convention Skill can automatically activate. Since the Skill's knowledge is injected together into the main conversation context where the Command runs, it combines so that the commit message is written by referencing the coding conventions during the commit.

Q. What is the difference between context: fork and a Subagent?

A. Both run in a separate context, but context: fork is an option of a Skill, while a Subagent is an independent agent. A Skill + context: fork is suitable for running a single task in isolation, whereas a Subagent is suitable when you need fine-grained control such as tool restriction, model selection, and Skill preloading.

9. Conclusion

The reason Command, Skill, and Subagent are confusing is that all three share the commonality of "customizing Claude's behavior." Summarizing the differences in one line each:

• Command: "When I tell you to, run this procedure" (e.g., /commit, /plan-task)
• Skill: "Refer to this field's specialized knowledge when needed" (e.g., go-convention, go-project-layout)
• Subagent: "Hand this type of work to a separate specialist" (e.g., code-reviewer, debugger, test-runner)
• Subagent + Skill: "Hand it to a specialist equipped with specialized knowledge" (e.g., api-developer + api-convention)

The full directory structure of this article is as follows.

.claude/
├── commands/
│   ├── commit.md              # Example 1: Git Commit automation
│   ├── plan-task.md           # Example 2: PRD → implementation doc generation
│   └── start-task.md          # Example 3: Starting a task
├── skills/
│   ├── go-convention/
│   │   └── SKILL.md           # Example 4: Go coding convention (auto-invocation)
│   ├── go-project-layout/
│   │   └── SKILL.md           # Example 5: Go project layout (dynamic context)
│   ├── analyze-codebase/
│   │   └── SKILL.md           # Example 6: Codebase analysis (context: fork)
│   └── api-convention/
│       └── SKILL.md           # Example 7: API convention (Subagent-only)
└── agents/
    ├── code-reviewer.md       # Example 8: Code review (read-only)
    ├── debugger.md            # Example 9: Debugging (can modify)
    ├── test-runner.md         # Example 10: Test execution (haiku, no modification)
    └── api-developer.md       # Example 11: API development (Skill combination)

10. References

• Claude Code: Skills, Commands, Subagents, and Plugins
• Claude Code Customization Guide
• Claude Code Skills, Commands, Subagents 정리
• Skills explained: How Skills compares to prompts, Projects, MCP, and subagents
• Skills explained 번역
• Claude Code Skills vs Plugins
• tutorials-go/.claude 예제 코드

In the previous article, Claude Code 확장 기능 완벽 가이드: Command, Skill, Subagent, we covered the concepts and practical usage of Claude Code's three core extension features: Command, Skill, and Subagent. In this article, without overlap, we organize new content centered on the next steps: Hooks (event-driven automation) and the Plugin system (packaging and distributing extensions).

1.1 Standalone Configuration vs Plugin

Individual extensions can be configured directly in the .claude/ directory and used immediately. However, if you want to share them with your team or distribute them to the community, packaging them as a Plugin is more efficient.

In this article, we first cover the concept and practical usage of Hooks, then explain how to package all extensions into one with the Plugin system.

2. Hooks (Event-Driven Automation)

2.1 What Are Hooks

Hooks are an automation mechanism that executes deterministically in response to specific Claude Code events. The key point is that, rather than relying on the LLM's judgment, they always behave identically according to predefined rules.

Key characteristics:

• Deterministic execution: The LLM does not decide "whether or not" to run. If conditions match, it always executes
• Event-driven: Can intervene at 14 points such as before/after tool calls, session start/end, etc.
• Blocking capability: Certain Hooks can block dangerous operations before they execute
• Three handler types: shell command (command), LLM single turn (prompt), subagent (agent)

For example, if you want to "prevent accidentally running rm -rf /," you could write "do not use rm -rf" in CLAUDE.md, but the LLM may ignore it. With Hooks, you can inspect the command before the Bash tool call and block it with 100% certainty.

flowchart LR
    A["Event occurs\n(e.g. Bash call)"] --> B{"matcher pattern\nmatches?"}
    B -- No --> C["Skip Hook"]
    B -- Yes --> D["Run Hook\n(command/prompt/agent)"]
    D --> E{"Check exit code"}
    E -- "0 (success)" --> F["Continue event"]
    E -- "2 (block)" --> G["Block event\n+ stderr feedback"]

    style G fill:#fce8e6,stroke:#d93025
    style F fill:#d4edda,stroke:#28a745

2.2 The 14 Hook Events

Claude Code provides 14 events across the full session lifecycle. Each event falls into one of two categories depending on whether it can block.

When a Hook returns exit code 2 on a blocking event, that operation is aborted and the contents of stderr are passed to Claude as feedback.

Common fields in the stdin JSON passed to a Hook:

{
  "session_id": "abc123",
  "cwd": "/home/user/my-project",
  "hook_event_name": "PreToolUse",
  "tool_name": "Bash",
  "tool_input": {
    "command": "npm test"
  }
}

2.3 How to Configure Hooks

2.3.1 Configuration Format

Hooks are configured in JSON format. The structure is event → matcher → hooks array.

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "bash .claude/hooks/block-dangerous-commands.sh"
          }
        ]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "bash .claude/hooks/auto-lint.sh"
          }
        ]
      }
    ]
  }
}

2.3.2 matcher Patterns

matcher is a regular expression pattern that filters which tool names the Hook reacts to.

2.3.3 Configuration Locations & Scope

Hooks can be configured in 4 locations, each with a different scope of application.

Hooks from all scopes are merged and executed. If multiple Hooks are configured for the same event, they all run in order.

2.4 The Three Hook Handler Types

When a Hook is triggered, you can choose among 3 handlers depending on what to execute.

2.4.1 command (Shell Command)

The most basic handler, which directly runs a shell command. Event data is passed as JSON via stdin.

{
  "type": "command",
  "command": "bash .claude/hooks/block-rm.sh"
}

• exit code 0: Success (event continues)
• exit code 2: Block (blocking events only). stderr content is passed to Claude as feedback
• stdout output: Passed to Claude as additional context (useful in non-blocking Hooks)
• Timeout: Default 600 seconds, adjustable via the timeout field (prompt is 30 seconds, agent is 60 seconds)
• Async execution: Setting "async": true proceeds without waiting for the Hook to complete
• Environment variables: $CLAUDE_PROJECT_DIR (project root) and ${CLAUDE_PLUGIN_ROOT} (Plugin root) are available

2.4.2 prompt (LLM Single Turn)

A handler that requests a single-turn evaluation from the LLM. It analyzes and judges the event data without using tools.

{
  "type": "prompt",
  "prompt": "Review the result of the following task and judge whether the goal was achieved. If not achieved, tell me what is missing."
}

• The LLM receives the event context and generates a single response
• Since it cannot use tools, it is suitable for reading/analysis purposes
• Useful when combined with the Stop event to judge whether a task is complete

2.4.3 agent (Subagent Multi-Turn)

A handler that creates a subagent to perform multi-turn validation tasks.

{
  "type": "agent",
  "prompt": "Read the file that was just modified, check the code style guide, and report any violations."
}

• The subagent can use tools to read files, search, etc.
• More costly than prompt, but suitable for complex validation
• Useful when you need to read and analyze multiple files

2.5 Practical Examples

2.5.1 Blocking Dangerous Commands (PreToolUse + Bash)

Block dangerous commands like rm -rf / and git push --force before the Bash tool call.

settings.json:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "bash .claude/hooks/block-dangerous-commands.sh"
          }
        ]
      }
    ]
  }
}

.claude/hooks/block-dangerous-commands.sh:

#!/bin/bash
# Event data is passed as JSON via stdin
input=$(cat)
command=$(echo "$input" | jq -r '.tool_input.command // empty')

# Check for dangerous command patterns
dangerous_patterns=(
  "rm -rf /"
  "rm -rf ~"
  "git push.*--force.*main"
  "git push.*--force.*master"
  "DROP TABLE"
  "DROP DATABASE"
)

for pattern in "${dangerous_patterns[@]}"; do
  if echo "$command" | grep -qE "$pattern"; then
    echo "Dangerous command blocked: $command" >&2
    echo "This command was blocked by security policy." >&2
    exit 2  # exit code 2 = block
  fi
done

exit 0  # exit code 0 = allow

Behavior scenario: When Claude tries to run rm -rf /tmp/build, the Hook inspects the command and allows it since it does not match a dangerous pattern. On the other hand, if it tries git push --force origin main, it is blocked with exit code 2, and the feedback "This command was blocked by security policy" is passed to Claude.

2.5.2 Auto-Linting After File Save (PostToolUse + Write|Edit)

Automatically run a linter after creating or modifying a file.

settings.json:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "bash .claude/hooks/auto-lint.sh"
          }
        ]
      }
    ]
  }
}

.claude/hooks/auto-lint.sh:

#!/bin/bash
input=$(cat)
file_path=$(echo "$input" | jq -r '.tool_input.file_path // .tool_input.path // empty')

if [ -z "$file_path" ]; then
  exit 0
fi

# Run the appropriate linter based on file extension
case "$file_path" in
  *.ts|*.tsx)
    npx eslint --fix "$file_path" 2>/dev/null
    ;;
  *.py)
    ruff check --fix "$file_path" 2>/dev/null
    ;;
  *.go)
    gofmt -w "$file_path" 2>/dev/null
    ;;
esac

exit 0

Point: Since PostToolUse is a non-blocking event, returning exit code 2 does not abort the operation. The linter's results are passed to Claude via stdout.

2.5.3 Task Completion Validation (Stop + prompt handler)

When Claude is about to finish a response, the prompt handler validates whether the task is complete.

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "prompt",
            "prompt": "Review the task that was just completed. Comparing it to the user's original request: 1) Were all requirements met? 2) Was this a change requiring tests, but tests were not written? 3) Is anything missing? If anything is lacking, tell me specifically."
          }
        ]
      }
    ]
  }
}

Behavior scenario: When Claude processes a request like "add a function" and is about to finish its response, the Stop Hook asks the LLM to review. If the LLM judges that "tests are missing," that feedback is passed to Claude, which then continues with additional work.

2.5.4 MCP Tool Monitoring (mcp__*__ matcher)

Monitor and log tool calls of an MCP server.

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "mcp__memory__.*",
        "hooks": [
          {
            "type": "command",
            "command": "bash -c 'echo \"[$(date)] MCP memory tool call: $(cat | jq -r .tool_name)\" >> /tmp/mcp-audit.log'"
          }
        ]
      }
    ]
  }
}

2.5.5 Asynchronous Test Execution (async: true)

After a file change, run tests asynchronously so they do not block Claude's next task.

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "bash -c 'npm test -- --related $(cat | jq -r .tool_input.file_path) &>/tmp/test-results.log'",
            "async": true,
            "timeout": 120000
          }
        ]
      }
    ]
  }
}

Point: Setting async: true means it does not wait until the Hook finishes executing. This is suitable for time-consuming tasks like tests.

2.6 Hooks Best Practices

2.6.1 Recommended Use Case Collection

2.6.2 Design Principles

1. Use the command handler by default

For tasks with clear rules, such as linting, formatting, and pattern checking, command is the most efficient. Use prompt or agent only when judgment is required, since they incur LLM cost.

2. Block minimally, give clear feedback

When blocking with exit code 2, you should specifically explain why it was blocked in stderr so that Claude can find an alternative.

# ❌ Bad example: blocking without a reason
echo "Blocked" >&2 && exit 2

# ✅ Good example: provide a specific reason and alternative
echo "You cannot push directly to the main branch. Create a PR from a feature branch." >&2 && exit 2

3. Run heavy tasks with async

For time-consuming tasks like running tests or validating builds, set "async": true so they do not block Claude's workflow.

4. Make Hook scripts exit quickly

Synchronous Hooks block Claude's response. Do not rely on the default timeout (command: 600 seconds); write the script itself to finish as quickly as possible.

5. Narrow the event + matcher combination precisely

If you omit the matcher, the Hook runs for all tools of that event. To reduce unnecessary execution, specify the matcher as specifically as possible.

// ❌ Run lint on all tools (unnecessary)
{ "matcher": null }

// ✅ Run lint only on file-modifying tools
{ "matcher": "Write|Edit" }

3. Plugin System

3.1 What Is a Plugin

A Plugin is a packaging system that bundles Skills, Hooks, Agents, MCP servers, and LSP servers into a single distribution unit. Instead of configuring individual extensions directly, packaging them as a Plugin makes installation, updates, and sharing easy.

Key characteristics:

• Unified packaging: Bundles Command, Skill, Agent, Hook, MCP, and LSP into one
• Namespacing: Prevents name collisions with the /plugin-name:skill-name format
• One-click install: Install via the /plugins command or Marketplace
• Auto-update: Supports version management and auto-update when registered on a Marketplace
• Scope selection: Choose among user global, project shared, or project local

3.2 Plugin Structure

3.2.1 Directory Layout

my-plugin/
├── .claude-plugin/
│   └── plugin.json         # Manifest (required)
├── commands/               # Slash commands (markdown files)
│   └── deploy.md
├── skills/                 # Agent Skills
│   └── code-review/
│       └── SKILL.md
├── agents/                 # Custom subagents
│   └── reviewer.md
├── hooks/
│   └── hooks.json          # Event handlers
├── .mcp.json               # MCP server config
└── .lsp.json               # LSP server config

All directories are optional. You only need to include the extensions you need. The only required file is .claude-plugin/plugin.json.

3.2.2 plugin.json Manifest Schema

{
  "name": "my-awesome-plugin",
  "description": "A Plugin that automates the project development workflow",
  "version": "1.0.0",
  "author": {
    "name": "Developer Name",
    "url": "https://github.com/username"
  },
  "homepage": "https://github.com/username/my-awesome-plugin",
  "repository": "https://github.com/username/my-awesome-plugin",
  "license": "MIT"
}

3.3 Plugin Development Workflow

3.3.1 Local Testing (--plugin-dir)

When developing a Plugin, you can test it locally right away.

# Load a single Plugin
claude --plugin-dir ./my-plugin

# Load multiple Plugins at once
claude --plugin-dir ./plugin-one --plugin-dir ./plugin-two

A Plugin loaded with --plugin-dir behaves the same as a regular installation. Skills can be invoked in the /plugin-name:skill-name format, and Hooks also work as configured.

3.3.2 Migrating Existing .claude/ Configuration to a Plugin

If you already have extensions configured in the .claude/ directory, you can convert them to a Plugin with a simple structural transformation.

Migration steps:

1. Create the Plugin directory and write plugin.json
2. Copy existing files into the new structure
3. Separate the hooks from settings.json into hooks/hooks.json
4. Test with --plugin-dir
5. Remove the existing .claude/ configuration (optional)

3.4 LSP Server (Code Intelligence)

A Plugin can include an LSP (Language Server Protocol) server to provide real-time code intelligence. The LSP server provides Claude with features such as code diagnostics (errors, warnings), autocompletion, and go-to-definition.

3.4.1 .lsp.json Configuration

{
  "mcpServers": {
    "typescript-lsp": {
      "command": "npx",
      "args": ["typescript-language-server", "--stdio"],
      "languages": ["typescript", "typescriptreact"]
    },
    "python-lsp": {
      "command": "pylsp",
      "args": [],
      "languages": ["python"]
    }
  }
}

When the LSP server is enabled, Claude can reference real-time diagnostic information when modifying code. It detects compile errors or type errors and recognizes problems before making fixes.

3.4.2 Official LSP Plugins

The official Anthropic Marketplace provides LSP Plugins for 11 languages.

When an LSP Plugin is enabled, Claude automatically receives diagnostic information (errors, warnings) after modifying a file, allowing it to recognize problems without running the compiler directly.

4. Plugin Marketplace

4.1 Official Marketplace

Anthropic operates an official Plugin Marketplace (anthropics/claude-plugins-official), which provides curated Plugins. It is available automatically when Claude Code starts.

Characteristics of the official Marketplace:

• Includes only Plugins verified by Anthropic
• Connected by default when Claude Code is installed
• Browse and install directly via the /plugins command

4.2 Installing Plugins

4.2.1 /plugins Command

Running the /plugins command in Claude Code opens the Plugin management interface. You can search for and install Plugins from the Marketplace.

4.2.2 Installation Scope

When installing a Plugin, you choose one of 3 scopes.

4.2.3 Installing via CLI

# Install from the Marketplace
claude plugin install <plugin-name>

# Install directly from a GitHub repo
claude plugin install github:username/repo-name

# Install from a local path
claude plugin install /path/to/local/plugin

4.2.4 Plugin Management CLI Commands

4.3 Creating & Distributing a Marketplace

4.3.1 Using a GitHub Repo as a Marketplace

A community Marketplace can be run on top of a GitHub repo. Just create a marketplace.json file at the repo root.

{
  "name": "my-marketplace",
  "owner": {
    "name": "DevTools Team",
    "email": "devtools@example.com"
  },
  "metadata": {
    "description": "Team-only Plugin Marketplace",
    "version": "1.0.0"
  },
  "plugins": [
    {
      "name": "my-plugin",
      "description": "Plugin description",
      "source": {
        "source": "github",
        "repo": "username/my-plugin"
      },
      "tags": ["workflow", "automation"]
    },
    {
      "name": "local-plugin",
      "description": "Local path Plugin",
      "source": "./plugins/local-plugin"
    }
  ]
}

4.3.2 Registering a Marketplace

How users add a community Marketplace:

You can add it from the Marketplace tab via /plugins within Claude Code, or add it via the CLI.

# Add by GitHub repo
/plugin marketplace add username/marketplace-repo

# Add by Git URL (GitLab, Bitbucket, etc.)
/plugin marketplace add https://gitlab.com/org/marketplace-repo.git

# Pin to a specific branch/tag
/plugin marketplace add https://github.com/org/plugins.git#v1.0.0

In team projects, you can configure the Marketplace in .claude/settings.json so that teammates use it automatically.

{
  "extraKnownMarketplaces": {
    "company-tools": {
      "source": {
        "source": "github",
        "repo": "your-org/claude-plugins"
      }
    }
  },
  "enabledPlugins": {
    "code-formatter@company-tools": true,
    "deployment-tools@company-tools": true
  }
}

4.3.3 Distribution Checklist

Things to check when distributing a Plugin:

1. Complete the .claude-plugin/plugin.json manifest
2. Write a README.md (installation, usage, configuration options)
3. Apply Semantic Versioning (match the Git tag with the version field)
4. Check whether sensitive information (API keys, personal paths) is included
5. Complete local testing with --plugin-dir
6. Push to a public GitHub repo

5. Agent Teams (Experimental Feature)

5.1 Overview

Agent Teams is an experimental feature that coordinates multiple Claude Code instances as a team. One session takes the role of Team Lead, distributing work, and multiple Teammates work independently before sharing their results.

The key difference from Subagent is that direct communication between Teammates is possible.

flowchart TD
    Lead["Team Lead\n(coordination only)"]
    T1["Teammate 1\nSecurity review"]
    T2["Teammate 2\nPerformance analysis"]
    T3["Teammate 3\nTest validation"]
    TL["Shared task list"]

    Lead --> T1
    Lead --> T2
    Lead --> T3
    T1 <--> T2
    T2 <--> T3
    T1 <--> T3
    T1 --- TL
    T2 --- TL
    T3 --- TL

    style Lead fill:#e8f4fd,stroke:#1a73e8
    style TL fill:#fff3cd,stroke:#ffc107

5.2 Enabling & Usage

5.2.1 Enabling

Agent Teams is disabled by default. Enable it via an environment variable or settings.json.

{
  "env": {
    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
  }
}

5.2.2 Creating a Team

Request the team composition from Claude in natural language.

Create an agent team to review PR #142.
- 1 person responsible for reviewing security vulnerabilities
- 1 person responsible for analyzing performance impact
- 1 person responsible for verifying test coverage
Each reviews and shares the results.

5.2.3 Delegate Mode

Pressing Shift+Tab switches to Delegate mode. In this mode, the Team Lead does not modify code directly and performs only coordination work.

• Creating and managing Teammates
• Assigning tasks and checking status
• Relaying messages and synthesizing results
• Delegating code modification, file creation, etc. to Teammates

5.2.4 Display Modes

{
  "teammateMode": "in-process"
}

5.3 Suitable Use Cases & Limitations

5.3.1 Suitable Cases

• Research & review: Investigate from multiple perspectives simultaneously (security, performance, UX)
• Cross-layer work: Assign frontend, backend, and tests to different Teammates
• Competing-hypothesis debugging: Verify multiple hypotheses simultaneously and have them refute each other
• New module/feature development: Develop independent modules in parallel

5.3.2 Limitations

• No session resume: in-process Teammates cannot be restored with /resume or /rewind
• One team per session: Only one team can run at a time
• No nesting: Teammates cannot create their own teams
• Fixed Lead: The session that created the team is permanently the Lead role
• Watch for file conflicts: If multiple Teammates modify the same file, overwrites occur
• Token cost: Since each Teammate needs a separate context, the cost increases significantly

6. Security & Enterprise Management

6.1 Hook Security Considerations

Hooks run with the user's system privileges. Therefore, you must be especially careful about security.

• Input validation: Always validate the JSON data passed via stdin when parsing it
• Path traversal defense: When handling file paths in a Hook script, prevent path traversal attacks such as ..
• Sensitive file protection: Block commands that access .env, .git/, API key files, etc.
• Timeout setting: Set the timeout field to prevent infinite loops

6.2 Enterprise Management Settings

In an enterprise environment, IT administrators can control extensions centrally.

6.2.1 managed-mcp.json

IT administrators centrally deploy MCP servers across the entire organization. The organization's standard tools are provided automatically, without users having to configure them individually.

6.2.2 MCP Server Allow/Deny Lists

{
  "allowedMcpServers": ["github", "jira", "slack"],
  "deniedMcpServers": ["*"]
}

• allowedMcpServers: List of allowed MCP servers
• deniedMcpServers: List of blocked MCP servers (block all with *, then use only the allow list)

6.2.3 allowManagedHooksOnly

{
  "allowManagedHooksOnly": true
}

When this setting is enabled, all user- or project-level Hooks are ignored, and only Hooks set by the administrator are run. It is useful in security-critical enterprise environments.

6.2.4 strictKnownMarketplaces

{
  "strictKnownMarketplaces": true
}

When this setting is enabled, Plugins can be installed only from Marketplaces approved by the administrator. It prevents installing Plugins from unknown sources.

7. Conclusion

Including the Command, Skill, and Subagent covered in the previous article, when we put together Claude Code's 5 extension mechanisms, you can choose among them depending on the situation as follows.

flowchart TD
    A["Do you need an extension?"] -- Yes --> B["Which type?"]
    A -- No --> Z["Use plain Claude Code"]

    B --> C["Automate repetitive tasks"]
    B --> D["Inject knowledge/rules"]
    B --> E["Delegate independent work"]
    B --> F["Event automation"]
    B --> G["Team sharing/distribution"]

    C --> C1["Command\n(/commit, /deploy)"]
    D --> D1["Skill\n(coding conventions, project rules)"]
    E --> E1["Subagent\n(code review, debugging)"]
    F --> F1["Hooks\n(linting, command blocking)"]
    G --> G1["Plugin\n(package everything)"]

    style C1 fill:#d4edda,stroke:#28a745
    style D1 fill:#e8f4fd,stroke:#1a73e8
    style E1 fill:#fce8e6,stroke:#d93025
    style F1 fill:#fff3cd,stroke:#ffc107
    style G1 fill:#e8daef,stroke:#8e44ad

Summarizing the growth path in practice:

1. Start with Command: Automate repetitive tasks as slash commands
2. Inject knowledge with Skill: Teach Claude your project rules
3. Delegate with Subagent: Separate independent work to specialized agents
4. Automate with Hooks: Add event-driven deterministic validation
5. Package with Plugin: Bundle all extensions into one and share with your team

8. References

• Claude Code Hooks Reference
• Claude Code Hooks Guide
• Claude Code Plugins
• Claude Code Plugins Reference
• Discover and Install Plugins
• Plugin Marketplaces
• Agent Teams
• Claude Code Official Plugin Marketplace Guide
• Improving your coding workflow with Claude Code Plugins
• Claude Code Agent Teams - Addy Osmani
• From Tasks to Swarms: Agent Teams
• Claude Code 확장 기능 완벽 가이드: Command, Skill, Subagent

In this part, we fully cover channels — from basic behavior to the buffered/unbuffered difference, direction restrictions, and close rules.

1. Channel Concept and Creation

A channel is created with the make function. Think of it as a typed pipe.

ch := make(chan int)       // unbuffered channel (int type)
ch := make(chan string, 5) // buffered channel (string type, buffer size 5)

2. Send / Receive Behavior

To send a value to a channel, use the <- operator.

ch <- 42    // send: send 42 to the channel
val := <-ch // receive: receive a value from the channel

func TestChannelSendReceive(t *testing.T) {
    ch := make(chan int)

    go func() {
        ch <- 42 // send
    }()

    value := <-ch // receive (blocks until sent)
    assert.Equal(t, 42, value)
}

Channels support various types. Passing a struct lets you send a result and an error together.

func TestChannelStructType(t *testing.T) {
    type Result struct {
        Value int
        Err   error
    }

    ch := make(chan Result)

    go func() {
        ch <- Result{Value: 100, Err: nil}
    }()

    result := <-ch
    assert.Equal(t, 100, result.Value)
    assert.NoError(t, result.Err)
}

3. Understanding Blocking Behavior

The most important characteristic of a channel is blocking.

• Unbuffered channel: send and receive must be ready at the same time to proceed
• Buffered channel: send blocks when the buffer is full; receive blocks when the buffer is empty

graph LR
    subgraph "Unbuffered Channel"
        GA[Goroutine A<br/>send - blocking] -- "handshake<br/>(proceed together)" --> GB[Goroutine B<br/>receive - blocking]
    end

graph LR
    subgraph "Buffered Channel (size 3)"
        GA2[Goroutine A<br/>3 sends OK<br/>4th send BLOCK!] --> BUF[Buffer<br/>size: 3] --> GB2[Goroutine B<br/>receive]
    end

4. Unbuffered vs Buffered Channel

Unbuffered Channel

ch := make(chan int) // buffer size 0

• when you send, it blocks until the receiver receives
• synchronous communication: both sides must be ready to proceed

func TestUnbufferedChannel(t *testing.T) {
    ch := make(chan int)

    go func() {
        ch <- 42 // blocks here until the receiver is ready
    }()

    time.Sleep(100 * time.Millisecond) // the sender is already blocking
    value := <-ch                       // the moment we receive, the sender proceeds too
    assert.Equal(t, 42, value)
}

Buffered Channel

ch := make(chan int, 3) // buffer size 3

• if there's free space in the buffer, send completes immediately
• send blocks when the buffer is full
• asynchronous communication

func TestBufferedChannel(t *testing.T) {
    ch := make(chan int, 3)

    // can send up to 3 even without a receiver
    ch <- 1
    ch <- 2
    ch <- 3
    // ch <- 4 → blocking (buffer full)

    assert.Equal(t, 1, <-ch)
    assert.Equal(t, 2, <-ch)
    assert.Equal(t, 3, <-ch)
}

cap and len

func TestBufferedChannelCapLen(t *testing.T) {
    ch := make(chan string, 5)

    assert.Equal(t, 5, cap(ch)) // buffer capacity
    assert.Equal(t, 0, len(ch)) // number of values currently waiting

    ch <- "a"
    ch <- "b"

    assert.Equal(t, 5, cap(ch))
    assert.Equal(t, 2, len(ch))
}

When to Use Which?

5. Channel Direction Restrictions

You can restrict a channel's direction in a function parameter.

chan<- int  // send-only (can only send)
<-chan int  // receive-only (can only receive)

This lets you prevent incorrect use of a channel at compile time.

// producer: send-only channel
func produce(ch chan<- int, values []int) {
    for _, v := range values {
        ch <- v
    }
    close(ch)
}

// consumer: receive-only channel
func consume(ch <-chan int) []int {
    var results []int
    for v := range ch {
        results = append(results, v)
    }
    return results
}

func TestChannelDirection(t *testing.T) {
    ch := make(chan int, 5)
    go produce(ch, []int{1, 2, 3, 4, 5})
    results := consume(ch)
    assert.Equal(t, []int{1, 2, 3, 4, 5}, results)
}

A bidirectional channel is implicitly converted to send-only or receive-only. Conversion in the opposite direction causes a compile error.

var sendOnly chan<- int = ch  // OK: bidirectional → send-only
var recvOnly <-chan int = ch  // OK: bidirectional → receive-only

6. Channel Close

The Meaning of close

close(ch) is a declaration that "no more values will be sent to this channel."

Receiving from a Closed Channel

func TestReceiveFromClosedChannel(t *testing.T) {
    ch := make(chan int, 1)
    ch <- 42
    close(ch)

    // if there's a value in the buffer, it returns normally
    val, ok := <-ch
    assert.Equal(t, 42, val)
    assert.True(t, ok)       // a valid value

    // empty buffer and closed channel → zero value + false
    val, ok = <-ch
    assert.Equal(t, 0, val)  // int's zero value
    assert.False(t, ok)      // closed indicator
}

Close Rules

Close Responsibility Pattern

// pattern: the sender creates the channel, sends, and closes
func generator() <-chan int {
    ch := make(chan int)
    go func() {
        defer close(ch)   // the sender is responsible for closing
        for i := range 5 {
            ch <- i
        }
    }()
    return ch // return as receive-only
}

7. Range over Channel

Using range, values are automatically received until the channel is closed.

func TestRangeOverChannel(t *testing.T) {
    ch := make(chan int, 5)

    go func() {
        for i := 1; i <= 5; i++ {
            ch <- i
        }
        close(ch) // close is required for range to terminate!
    }()

    var results []int
    for v := range ch {
        results = append(results, v)
    }

    assert.Equal(t, []int{1, 2, 3, 4, 5}, results)
}

For range ch to terminate, close(ch) must be called. Without close, range blocks forever.

Signaling Channel

To send only a completion signal rather than data, use chan struct{}. struct{} takes up no memory.

func TestChannelSignaling(t *testing.T) {
    done := make(chan struct{})

    go func() {
        // do work...
        close(done) // completion signal (delivered to all receivers)
    }()

    <-done // wait for completion
}

close(done) sends a signal to all receivers simultaneously. This is the difference from simply doing done <- struct{}{}.

If you're confused about the difference between struct{} and struct{}{}, see the FAQ.

8. Practice: Producer / Consumer Pattern

func TestProducerConsumer(t *testing.T) {
    ch := make(chan int, 10)
    var results []int

    // Producer: generate squares
    go func() {
        for i := 1; i <= 10; i++ {
            ch <- i * i
        }
        close(ch)
    }()

    // Consumer: collect results
    for val := range ch {
        results = append(results, val)
    }

    expected := []int{1, 4, 9, 16, 25, 36, 49, 64, 81, 100}
    assert.Equal(t, expected, results)
}

Multiple Producers

func TestMultipleProducers(t *testing.T) {
    ch := make(chan int, 20)
    var wg sync.WaitGroup

    // 3 producers
    for p := range 3 {
        wg.Add(1)
        go func() {
            defer wg.Done()
            for i := range 5 {
                ch <- p*100 + i
            }
        }()
    }

    // close the channel once all producers finish
    go func() {
        wg.Wait()
        close(ch)
    }()

    var results []int
    for val := range ch {
        results = append(results, val)
    }

    assert.Len(t, results, 15) // 3 x 5 = 15 items
}

9. Summary

In the next part, we'll cover advanced channel patterns such as the select statement, which handles multiple channels simultaneously, and fan-in/fan-out.

FAQ

Q. What's the difference between struct{} and struct{}{}?

struct{} is a type, and struct{}{} is a value (instance).

It's easier to understand by analogy with a regular struct:

type Person struct {
    Name string
    Age  int
}

p := Person{Name: "Frank", Age: 30}
//   ^^^^^^ type
//         ^^^^^^^^^^^^^^^^^^^^^^^^ value

Likewise, an empty struct has the same structure:

v := struct{}{}
//   ^^^^^^^^ type: struct{} (a struct with no fields)
//           ^^ value: {} (empty literal)

When used with a channel:

// create a channel — specify the type
done := make(chan struct{})  // a channel of type struct{}

// send a value — send a struct{}{} instance
done <- struct{}{}

// close — deliver a "closed" signal to all receivers instead of a value
close(done)

Since struct{} takes up 0 bytes of memory, it's the most efficient choice when you want to only deliver a signal without data.

References

• Go Tour - Channels
• Effective Go - Channels
• Go Blog - Pipelines and cancellation

When doing performance analysis in Go, we mainly use net/http/pprof or runtime/pprof. These are sufficient for checking the CPU usage or memory allocation at a specific point in time as a snapshot in a development environment, but in a production environment they have a few limitations.

• You have to collect profiles manually at the moment a problem occurs
• The collected profiles remain only as local files, making comparison over time difficult
• You cannot centrally manage profile data distributed across multiple instances

Continuous Profiling solves these limitations. It collects profile data with consistently low overhead in production, stores it in a central repository, and lets you query historical data anytime.

In this post, we'll get hands-on with how to integrate Grafana Pyroscope, a Continuous Profiling platform, into a Go application. We'll cover both collection methods — Push mode (SDK) and Pull mode (Alloy) — and walk through analyzing performance bottlenecks with flame graphs.

The full code used in this post can be found on GitHub.

2. Continuous Profiling Overview

2.1 Traditional Profiling vs Continuous Profiling

Traditional profiling collects data manually after a problem occurs, whereas Continuous Profiling always collects data, so you can immediately check the profile at the moment a problem occurs.

2.2 Profile Types (Go)

The main profile types you can collect in Go are as follows.

The Mutex and Block profiles are disabled by default, so you have to enable them explicitly. In Push mode, set them before SDK initialization; in Pull mode, set them at application startup.

3. Grafana Pyroscope Architecture

3.1 Core Components

Pyroscope consists of the following microservice components, and runs as a single process in Monolithic mode.

flowchart LR
    Client["Client\n(SDK / Alloy)"]
    Dist["Distributor"]
    Ing["Ingester"]
    Store["Object Storage"]
    QF["Query Frontend"]
    Q["Querier"]
    SG["Store Gateway"]
    UI["Grafana UI"]

    Client --> Dist --> Ing --> Store
    UI --> QF --> Q --> Ing
    Q --> SG --> Store

3.2 Data Collection Methods: Push vs Pull

Pyroscope can collect profile data in two ways. Once the data reaches the Pyroscope server, the storage, querying, and flame graph analysis are completely identical regardless of which collection method you use. The only difference is the collection path.

flowchart TD
    subgraph push["Push Mode (SDK)"]
        App1["Go App\n+ pyroscope-go SDK"] -->|"direct send"| PS1["Pyroscope Server"]
    end

    subgraph pull["Pull Mode (Alloy)"]
        App2["Go App\n+ pprof endpoint"] <-->|"periodic scraping"| Alloy["Grafana Alloy"]
        Alloy -->|"send"| PS2["Pyroscope Server"]
    end

Practical tip: In a Kubernetes environment, if you already have many services that expose pprof, Pull mode is efficient. On the other hand, if you need fine-grained analysis like per-endpoint profiling, Push mode's TagWrapper is advantageous.

4. Setting Up a Local Environment

With Docker Compose, you can run the Pyroscope server, Grafana, and the Push/Pull mode sample applications all at once.

4.1 Docker Compose Configuration

services:
  # --- common infrastructure ---
  pyroscope:
    image: grafana/pyroscope:latest
    ports:
      - "4040:4040"
    networks:
      - pyroscope-net

  grafana:
    image: grafana/grafana:latest
    ports:
      - "3000:3000"
    environment:
      - GF_AUTH_ANONYMOUS_ENABLED=true
      - GF_AUTH_ANONYMOUS_ORG_ROLE=Admin
    volumes:
      - ./grafana/provisioning:/etc/grafana/provisioning
    depends_on:
      - pyroscope
    networks:
      - pyroscope-net

  # --- Push mode ---
  app-http:
    build:
      context: .
      dockerfile: http-server/Dockerfile
    ports:
      - "8080:8080"
    depends_on:
      - pyroscope
    environment:
      - PYROSCOPE_SERVER=http://pyroscope:4040
      - PORT=8080
    networks:
      - pyroscope-net

  # --- Pull mode ---
  app-pull:
    build:
      context: .
      dockerfile: pull-server/Dockerfile
    ports:
      - "6060:6060"
    environment:
      - PORT=6060
    networks:
      - pyroscope-net

  alloy:
    image: grafana/alloy:latest
    volumes:
      - ./alloy/config.alloy:/etc/alloy/config.alloy
    command: ["run", "/etc/alloy/config.alloy"]
    depends_on:
      - pyroscope
      - app-pull
    networks:
      - pyroscope-net

networks:
  pyroscope-net:
    driver: bridge

> docker compose up -d

4.2 Connecting the Grafana Data Source

You can automatically register the Pyroscope data source with Grafana provisioning settings.

# grafana/provisioning/datasources/pyroscope.yml
apiVersion: 1

datasources:
  - name: Pyroscope
    type: grafana-pyroscope-datasource
    url: http://pyroscope:4040
    isDefault: true
    editable: true

4.3 Access URLs

In Grafana, select the Explore menu → Pyroscope data source, and you can check the collected profile data as a flame graph. The Push mode app is shown as echo.server, and the Pull mode app as pull.golang.app.

5. Data Collection

5.1 Push Mode: SDK Integration

Push mode is a method where you add the Pyroscope Go SDK to the application and send profile data directly to the Pyroscope server.

5.1.1 Installing and Basic Setup of the SDK

> go get github.com/grafana/pyroscope-go

When you initialize the profiler with pyroscope.Start(), it continuously sends data of the configured profile types to the Pyroscope server while the application is running.

package main

import (
	"log"
	"os"
	"runtime"

	"github.com/grafana/pyroscope-go"
)

func main() {
	// mutex/blocking profiles are disabled by default, so enable them explicitly
	runtime.SetMutexProfileFraction(5)
	runtime.SetBlockProfileRate(5)

	profiler, err := pyroscope.Start(pyroscope.Config{
		ApplicationName: "simple.golang.app",       // the name shown in the Pyroscope UI
		ServerAddress:   "http://localhost:4040",    // the Pyroscope server address
		Logger:          pyroscope.StandardLogger,
		Tags:            map[string]string{"hostname": os.Getenv("HOSTNAME")},
		ProfileTypes: []pyroscope.ProfileType{
			pyroscope.ProfileCPU,           // CPU profile
			pyroscope.ProfileAllocObjects,  // memory allocation count
			pyroscope.ProfileAllocSpace,    // memory allocation size
			pyroscope.ProfileInuseObjects,  // number of objects currently in use
			pyroscope.ProfileInuseSpace,    // size of memory currently in use
			pyroscope.ProfileGoroutines,    // goroutines
			pyroscope.ProfileMutexCount,    // mutex contention count
			pyroscope.ProfileMutexDuration, // mutex contention time
			pyroscope.ProfileBlockCount,    // blocking count
			pyroscope.ProfileBlockDuration, // blocking time
		},
	})
	if err != nil {
		log.Fatalf("failed to start pyroscope: %v", err)
	}
	defer profiler.Stop() // send the last profile data on shutdown
}

5.1.2 Key Configuration Items

5.1.3 Profiling Labels (TagWrapper)

Note: Profiling Labels can be used only in Push mode. In Pull mode, only the default stack traces provided by pprof are collected, so custom label tagging is impossible. This is the biggest functional difference between Push/Pull mode.

Using Pyroscope's TagWrapper, you can tag a specific code path with a label. Tagged profile data can be filtered by label in the flame graph, so you can answer questions like "which endpoint uses a lot of CPU?"

pyroscope.TagWrapper(ctx,
	pyroscope.Labels("workload", "cpu"),
	func(c context.Context) {
		cpuWork() // tag the profile data of this block with the workload=cpu label
	})

5.1.4 Per-Endpoint Profiling

In an Echo HTTP server, if you wrap each handler with TagWrapper, you can analyze the performance of each endpoint individually.

func handleSlow(c echo.Context) error {
	start := time.Now()

	pyroscope.TagWrapper(c.Request().Context(),
		pyroscope.Labels("endpoint", "/slow"),
		func(ctx context.Context) {
			fibonacci(38) // CPU-intensive computation
		})

	return c.JSON(http.StatusOK, response{
		Message: "slow response (CPU intensive)",
		Elapsed: time.Since(start).String(),
	})
}

func handleMemory(c echo.Context) error {
	start := time.Now()

	pyroscope.TagWrapper(c.Request().Context(),
		pyroscope.Labels("endpoint", "/memory"),
		func(ctx context.Context) {
			allocateMemory() // large memory allocation
		})

	return c.JSON(http.StatusOK, response{
		Message: "memory response (heap allocation)",
		Elapsed: time.Since(start).String(),
	})
}

When you query the Pyroscope data source in Grafana, you can filter the profiles of the /slow and /memory requests respectively by the endpoint label.

Below is the CPU profile flame graph of Push mode (echo.server). You can see at a glance that main.fibonacci takes up most of the CPU time.

In the memory profile, you can check the memory allocation pattern of main.allocateMemory.

5.2 Pull Mode: Alloy Integration

Pull mode is a method where, without changing the application code, Grafana Alloy periodically scrapes the existing net/http/pprof endpoint. It's the same concept as Prometheus's Pull method.

5.2.1 Application-Side Setup

In Pull mode, the application only needs to expose the pprof endpoint. There's no need to add the Pyroscope SDK.

import (
	"net/http"
	_ "net/http/pprof" // automatically registers the /debug/pprof/* endpoints
)

func main() {
	http.ListenAndServe(":6060", nil)
}

5.2.2 Grafana Alloy Configuration

Alloy is a telemetry collector made by Grafana, and it handles Pyroscope's Pull mode collection. Define the scrape targets in the config.alloy file.

// config.alloy
pyroscope.scrape "default" {
  targets = [
    {"__address__" = "app-pull:6060", "service_name" = "pull.golang.app"},
  ]

  scrape_interval = "15s"  // scrape every 15 seconds

  profiling_config {
    profile.process_cpu { enabled = true }           // CPU profile
    profile.memory {                                  // memory profile
      enabled = true
      path    = "/debug/pprof/allocs"
    }
    profile.goroutine { enabled = true }              // goroutine profile
    profile.mutex { enabled = true }                  // mutex profile
    profile.block { enabled = true }                  // blocking profile
  }

  forward_to = [pyroscope.write.endpoint.receiver]    // target to send the collected data
}

pyroscope.write "endpoint" {
  endpoint {
    url = "http://pyroscope:4040"                     // the Pyroscope server address
  }
}

Since Alloy scrapes the pprof endpoint every 15 seconds, if you generate load and wait a moment, you can query the profile data as the pull.golang.app application in Grafana.

Below is the CPU profile of Pull mode (pull.golang.app). Just like Push mode, main.fibonacci is shown as the CPU bottleneck, but TagWrapper-based label filtering cannot be used.

5.3 Load Testing

Both Push/Pull modes can generate load with the same endpoints.

# --- Push mode (http://localhost:8080) ---
> curl http://localhost:8080/fast       # fast response (baseline)
> curl http://localhost:8080/slow       # CPU load
> curl http://localhost:8080/memory     # memory load

# --- Pull mode (http://localhost:6060) ---
> curl http://localhost:6060/fast       # fast response
> curl http://localhost:6060/slow       # CPU load
> curl http://localhost:6060/memory     # memory load

# Directly check the Pull mode pprof endpoint
> curl http://localhost:6060/debug/pprof/

6. Grafana Profiles Drilldown

Regardless of which collection method you use, the profile data stored on the Pyroscope server can be analyzed the same way. After generating load, you can check the collected profile data in Grafana's Drilldown > Profiles menu. Profiles Drilldown lets you progressively narrow the analysis scope in the order of service list → profile type → flame graph → labels.

6.1 All Services (Service List)

The first screen shows the profile data of all services registered in Pyroscope in a grid view.

In the Profile type dropdown at the top, you can switch profile types such as process_cpu/cpu and memory, and you can also filter by searching for a service name.

6.2 Profile Types (Status by Profile Type)

When you select a service, you can see at a glance all the profile types being collected from that service. Below is the Profile Types screen of echo.server.

Time-series graphs of each profile type — CPU, memory, goroutine, mutex, block, etc. — are displayed, so you can quickly grasp which resource has an anomaly. Clicking the Flame graph link on each card takes you to the detailed flame graph of that profile type.

6.3 Flame Graph (Detailed Analysis)

When you select a specific profile type, a flame graph is displayed along with a symbol table. In the symbol table, you can sort the Self time and Total time of each function to quickly identify the performance bottleneck function.

A flame graph is a graph that visualizes profiling data based on stack traces.

• Horizontal axis: the proportion of total time taken by that function (the wider, the more resources used)
• Vertical axis: the function call hierarchy (calls get deeper from top to bottom)
• Root node: 100% of the total application time

[              root (100%)                ]
[     funcA (60%)      ][   funcB (40%)   ]
[  funcC (30%) ][ funcD (30%) ]

The points to note when analyzing a flame graph are as follows.

• Wide block = a performance bottleneck candidate (much time is spent in that function)
• Deep stack = the call chain is deep (it doesn't necessarily mean a problem)
• Self time vs Total time: its own execution time vs the total time including subordinate functions

The main analysis features are as follows.

• Time range selection: analyze only the profile of a specific time interval
• Function click: filter centered on that function for detailed inspection
• Labels filtering: analyze only a specific code path with endpoint=/slow, etc. (when label tagging was done in Push mode)

6.4 Labels (Classification by Label)

In the Labels tab, you can view profile data grouped by label. You can separate and compare time series by labels tagged with TagWrapper in Push mode (e.g. hostname, pyroscope_spy).

6.5 Diff Flame Graph (Comparative Analysis)

In the Diff flame graph tab, you can compare the profiles of two time intervals side by side. When you select the Baseline and Comparison intervals respectively, it visualizes the performance difference before and after the change with colors (red=increase, green=decrease).

7. Practical Tips

7.1 Precautions When Applying in Production

• Overhead management: The CPU overhead of the Pyroscope SDK is about 2-5%. You can reduce GC-related overhead with the DisableGCRuns: true option
• Choosing profile types: Enabling all profiles increases overhead, so it's recommended to enable only CPU and memory profiles by default and add Mutex/Block when needed
• SetMutexProfileFraction and SetBlockProfileRate values: The smaller the value, the more events are recorded. In production, control overhead with a value of 5 or higher

7.2 Coexistence with Existing pprof Code

The Pyroscope Go SDK internally uses runtime/pprof. If you're already using net/http/pprof, you can use it together with the Pyroscope SDK.

import _ "net/http/pprof" // keep the existing pprof HTTP endpoints

// Add the Pyroscope SDK - also send the same profile data to the Pyroscope server
profiler, _ := pyroscope.Start(pyroscope.Config{...})
defer profiler.Stop()

A hybrid configuration is possible where you keep the existing pprof endpoints for ad-hoc debugging while collecting always-on profiling data with Pyroscope.

7.3 Push/Pull Mode Migration

You can add Push mode to a service already operating in Pull mode, or vice versa.

• Pull → Push transition: Add the SDK and remove that target from the Alloy configuration. Transition when you need fine-grained label tagging with TagWrapper.
• Push + Pull coexistence: You can expose pprof endpoints while pushing with the SDK. However, if Alloy scrapes the same service, the data will be duplicated, so it's recommended to enable only one collection method.

8. Conclusion

In this post, we covered Continuous Profiling for Go applications using Grafana Pyroscope.

• Continuous Profiling collects profiles continuously in production, solving the "manual collection after a problem occurs" limitation of traditional pprof
• Push mode (SDK) can be integrated with a single line, pyroscope.Start(), and enables fine-grained per-endpoint analysis with TagWrapper
• Pull mode (Alloy) leverages existing pprof endpoints without code changes, which is especially advantageous for bulk-collecting multiple services as a DaemonSet in a K8s environment
• Through flame graphs, you can quickly grasp performance bottlenecks visually, and check the performance difference before and after a change with the comparison/Diff view

The full code can be found on GitHub.

9. References

• Grafana Pyroscope official documentation
• Pyroscope Go SDK (Push mode)
• Grafana Alloy (Pull mode)
• Pyroscope GitHub repository
• pyroscope-go Go client
• What is Continuous Profiling?
• Flame Graph guide

1.Language Changes

1.1 new() Function Extension - Specifying an Initial Value

This is the most noticeable language change in Go 1.26. The previous new(T) could only create a pointer to a zero value, but now the new(expr) form lets you create a pointer with an initial value in a single line.

func TestNewWithExpression(t *testing.T) {
	// Old way: declare a variable first, then take its address
	x := 42
	pOld := &x
	fmt.Println("old way:", *pOld) // 42

	// New way: create a pointer directly with new(expr)
	pNew := new(42)
	fmt.Println("new way:", *pNew) // 42
}

You can also create pointers to slices and maps directly.

func TestNewWithSliceExpression(t *testing.T) {
	// Create a slice pointer
	ps := new([]int{11, 12, 13})
	fmt.Println(*ps) // [11 12 13]
}

func TestNewWithMapExpression(t *testing.T) {
	// Create a map pointer
	pm := new(map[string]int{"a": 1, "b": 2})
	fmt.Println(*pm) // map[a:1 b:2]
}

It is especially useful when assigning a pointer to a struct field. Previously you had to declare a separate variable, but now you can handle it in one line.

type Person struct {
	Name string
	Age  *int
}

func yearsSince(t time.Time) int {
	return int(time.Since(t).Hours() / 8766)
}

func TestNewInStructField(t *testing.T) {
	born := time.Date(1990, 1, 1, 0, 0, 0, 0, time.UTC)

	// Old way: a separate variable is needed
	age := yearsSince(born)
	p1 := Person{Name: "Alice", Age: &age}

	// New way: assign directly with new(expr)
	p2 := Person{Name: "Alice", Age: new(yearsSince(born))}

	fmt.Printf("old: %s, age %d\n", p1.Name, *p1.Age)
	fmt.Printf("new: %s, age %d\n", p2.Name, *p2.Age)
}

It can also be used cleanly in JSON marshaling.

func TestNewWithJSON(t *testing.T) {
	born := time.Date(1990, 1, 1, 0, 0, 0, 0, time.UTC)

	data, _ := json.Marshal(Person{
		Name: "Bob",
		Age:  new(yearsSince(born)),
	})
	fmt.Println(string(data)) // {"Name":"Bob","Age":36}
}

1.2 Recursive Type Constraints

A generic type can now reference itself as a type parameter. This makes it possible to implement the F-bounded polymorphism pattern.

1.2.1 What is F-bounded polymorphism?

F-bounded polymorphism is a pattern where an interface (type constraint) takes, as a parameter, a type that implements the interface itself. A normal generic constraint declares "T must have these methods," but an F-bounded constraint declares "T must have a method that takes its own type as an argument."

Normal constraint:     Comparable       → Equal(other any) bool
F-bounded constraint: Comparable[T]   → Equal(other T) bool   ← T refers to itself

The key advantage of this pattern is type safety. With a normal interface, Equal(other any) has to accept any type, which requires a type assertion at runtime. But with the F-bounded pattern, Equal(other T) guarantees at compile time that only values of the same type are compared.

It is a pattern widely used in other languages as well — Java's Comparable<T>, Rust's trait Add<Rhs = Self> — and Go supports it starting from Go 1.26.

// Ordered - a generic type referencing itself as a type parameter
type Ordered[T Ordered[T]] interface {
	Less(T) bool
}

type MyInt int

func (a MyInt) Less(b MyInt) bool {
	return a < b
}

// Min - a minimum function using recursive generics
func Min[T Ordered[T]](a, b T) T {
	if a.Less(b) {
		return a
	}
	return b
}

func TestRecursiveGenericMin(t *testing.T) {
	result := Min(MyInt(3), MyInt(7))
	fmt.Printf("Min(3, 7) = %d\n", result) // 3
}

It can also be used in practical patterns such as vector arithmetic.

// Adder - the F-bounded polymorphism pattern
type Adder[A Adder[A]] interface {
	Add(A) A
}

type Vector2D struct {
	X, Y float64
}

func (v Vector2D) Add(other Vector2D) Vector2D {
	return Vector2D{X: v.X + other.X, Y: v.Y + other.Y}
}

func Sum[A Adder[A]](values []A) A {
	var zero A
	result := zero
	for _, v := range values {
		result = result.Add(v)
	}
	return result
}

func TestAdderInterface(t *testing.T) {
	vectors := []Vector2D{{1, 2}, {3, 4}, {5, 6}}
	result := Sum(vectors)
	fmt.Printf("Sum = %+v\n", result) // {X:9 Y:12}
}

2.Performance Improvements

2.1 Green Tea Garbage Collector (Enabled by Default)

The Green Tea GC, introduced experimentally in Go 1.25, is enabled by default in Go 1.26. It improves the marking/scanning performance of small objects, reducing GC overhead by 10–40%.

Key characteristics:

• Significantly improved memory access efficiency
• An additional 10% improvement on recent CPUs (Intel Ice Lake, AMD Zen 4 and later)
• The disable option is scheduled to be removed in Go 1.27

# Disable (scheduled for removal in Go 1.27)
GOEXPERIMENT=nogreenteagc go build

2.2 30% Faster cgo Calls

By simplifying processor state management, the baseline runtime overhead of cgo calls has been reduced by about 30%.

# Benchmark comparison
Go 1.25: 28.55ns/op
Go 1.26: 19.02ns/op  (-33%)

2.3 io.ReadAll Is 2x Faster

The performance of io.ReadAll has improved roughly 2x and memory usage has dropped by 50%.

func BenchmarkReadAll_1MB(b *testing.B) {
	data := bytes.Repeat([]byte("x"), 1024*1024)
	for b.Loop() {
		io.ReadAll(bytes.NewReader(data))
	}
}

2.4 fmt.Errorf Is 92% Faster

A fmt.Errorf call with no format arguments has been optimized to 0 allocations, making it 92% faster than before.

func BenchmarkErrorf_NoFormat(b *testing.B) {
	// Optimized to 0 allocations in Go 1.26 (previously 2 allocations)
	for b.Loop() {
		_ = fmt.Errorf("simple error message")
	}
}

2.5 Optimized Memory Allocation for Small Objects

Allocation speed for small objects of 1–512 bytes has improved by up to 30%. Stack-based slice backing-store allocation has also been extended to more situations.

3.Major Standard Library Changes

3.1 errors.AsType - Type-Safe Error Inspection

The existing errors.As required you to declare the target variable in advance, but the new errors.AsType[T] provides generics-based, type-safe error inspection.

type AppError struct {
	Code    int
	Message string
}

func (e *AppError) Error() string {
	return fmt.Sprintf("[%d] %s", e.Code, e.Message)
}

func TestErrorsAs_OldWay(t *testing.T) {
	err := fmt.Errorf("wrapped: %w", &AppError{Code: 404, Message: "not found"})

	// Old way: the target variable must be declared in advance
	var target *AppError
	if errors.As(err, &target) {
		fmt.Printf("Code: %d, Message: %s\n", target.Code, target.Message)
	}
}

func TestErrorsAsType_NewWay(t *testing.T) {
	err := fmt.Errorf("wrapped: %w", &AppError{Code: 404, Message: "not found"})

	// New way: errors.AsType[T]() - type-safe, no variable declaration needed
	if target, ok := errors.AsType[*AppError](err); ok {
		fmt.Printf("Code: %d, Message: %s\n", target.Code, target.Message)
	}
}

It also works on nested error chains.

func TestErrorsAsType_ChainedErrors(t *testing.T) {
	innerErr := &ValidationError{Field: "email", Message: "invalid format"}
	wrappedErr := fmt.Errorf("outer: %w", fmt.Errorf("inner: %w", innerErr))

	// Type lookup even through a nested error chain
	if target, ok := errors.AsType[*ValidationError](wrappedErr); ok {
		fmt.Printf("Field: %s, Message: %s\n", target.Field, target.Message)
	}
}

3.2 reflect Iterators Added

Fields() and Methods() iterators have been added to reflect.Type, so you can iterate over fields and methods with a range loop.

func TestReflectFields(t *testing.T) {
	type User struct {
		Name  string
		Email string
		Age   int
	}

	typ := reflect.TypeFor[User]()

	// Old way: iterate by index
	for i := 0; i < typ.NumField(); i++ {
		f := typ.Field(i)
		fmt.Printf("%s: %s\n", f.Name, f.Type)
	}

	// New way: range iterator
	for f := range typ.Fields() {
		fmt.Printf("%s: %s\n", f.Name, f.Type)
	}
}

func TestReflectMethods(t *testing.T) {
	// Look up methods on a pointer type
	typ := reflect.TypeFor[*http.Client]()

	for m := range typ.Methods() {
		fmt.Printf("%s\n", m.Name)
	}
	// CloseIdleConnections, Do, Get, Head, Post, PostForm
}

3.3 bytes.Buffer.Peek() Method

A Peek method has been added that lets you inspect the next bytes without advancing the buffer. Unlike Read, it does not change the buffer position.

func TestBufferPeek(t *testing.T) {
	buf := bytes.NewBufferString("hello world")

	// Peek: inspect the next n bytes without advancing the buffer
	peeked, _ := buf.Peek(5)
	fmt.Printf("Peek(5): %q\n", peeked)   // "hello"
	fmt.Printf("Len: %d\n", buf.Len())     // 11 (unchanged)

	// Read: advances the buffer
	readBuf := make([]byte, 5)
	buf.Read(readBuf)
	fmt.Printf("Len after Read: %d\n", buf.Len()) // 6
}

3.4 slog.NewMultiHandler()

NewMultiHandler, which can write to multiple log handlers at once, has been added. It is useful when you want to use console and file, or text and JSON formats, simultaneously.

func TestSlogNewMultiHandler(t *testing.T) {
	var textBuf, jsonBuf bytes.Buffer

	textHandler := slog.NewTextHandler(&textBuf, nil)
	jsonHandler := slog.NewJSONHandler(&jsonBuf, nil)

	// NewMultiHandler: write to multiple handlers at once
	multi := slog.NewMultiHandler(textHandler, jsonHandler)
	logger := slog.New(multi)

	logger.Info("user login", "user", "alice", "ip", "192.168.1.1")

	fmt.Println("Text:", textBuf.String())
	// time=... level=INFO msg="user login" user=alice ip=192.168.1.1
	fmt.Println("JSON:", jsonBuf.String())
	// {"time":"...","level":"INFO","msg":"user login","user":"alice","ip":"192.168.1.1"}
}

You can also set a different level for each handler.

func TestSlogMultiHandlerWithLevels(t *testing.T) {
	var infoBuf, errorBuf bytes.Buffer

	infoHandler := slog.NewTextHandler(&infoBuf, &slog.HandlerOptions{Level: slog.LevelInfo})
	errorHandler := slog.NewTextHandler(&errorBuf, &slog.HandlerOptions{Level: slog.LevelError})

	multi := slog.NewMultiHandler(infoHandler, errorHandler)
	logger := slog.New(multi)

	logger.Info("info message")   // written only to infoBuf
	logger.Error("error message") // written to both handlers
}

3.5 testing.ArtifactDir() - Storing Test Artifacts

A t.ArtifactDir() method has been added that returns a directory for storing outputs generated during a test run (logs, screenshots, dumps, etc.).

func TestArtifactDir(t *testing.T) {
	dir := t.ArtifactDir()
	fmt.Printf("Artifact directory: %s\n", dir)

	// Save a test result file
	content := []byte("test output data")
	os.WriteFile(filepath.Join(dir, "output.txt"), content, 0644)
}

In CI environments, you can preserve artifacts on test failure and use them for debugging.

3.6 signal.NotifyContext and Context Cause

When a context created with signal.NotifyContext is canceled, you can check which signal was received via context.Cause.

func TestSignalNotifyContext(t *testing.T) {
	ctx, stop := signal.NotifyContext(context.Background(), os.Interrupt)
	defer stop()

	stop() // simulate cancellation

	select {
	case <-ctx.Done():
		cause := context.Cause(ctx)
		fmt.Printf("Cause: %v\n", cause) // context canceled
	}
}

func TestContextCauseBasic(t *testing.T) {
	ctx, cancel := context.WithCancelCause(context.Background())

	// Cancel with a specific cause
	cancel(fmt.Errorf("user requested cancellation"))

	cause := context.Cause(ctx)
	fmt.Printf("Context cause: %v\n", cause)
	// user requested cancellation
}

3.7 netip.Prefix.Compare - Sorting Subnets

A Compare method has been added to netip.Prefix, so you can sort CIDR-notation subnets with slices.SortFunc.

func TestNetipPrefixCompare(t *testing.T) {
	prefixes := []netip.Prefix{
		netip.MustParsePrefix("192.168.1.0/24"),
		netip.MustParsePrefix("10.0.0.0/8"),
		netip.MustParsePrefix("172.16.0.0/12"),
		netip.MustParsePrefix("10.0.1.0/24"),
		netip.MustParsePrefix("192.168.0.0/16"),
	}

	// Go 1.26: sort with netip.Prefix.Compare
	slices.SortFunc(prefixes, netip.Prefix.Compare)

	for _, p := range prefixes {
		fmt.Println(p)
	}
	// 10.0.0.0/8
	// 10.0.1.0/24
	// 172.16.0.0/12
	// 192.168.0.0/16
	// 192.168.1.0/24
}

You can also sort a mix of IPv4 and IPv6, with IPv4 sorted before IPv6.

4.Security and Cryptography

4.1 crypto/hpke Package (New)

An implementation of the RFC 9180 Hybrid Public Key Encryption (HPKE) standard has been added as a new package. It also supports post-quantum hybrid KEM.

4.2 Cryptographic API Improvements - io.Reader Removed

In functions of crypto/dsa, crypto/ecdh, crypto/ecdsa, crypto/rsa, crypto/rand, and others, the random parameter is now ignored and a secure random source is automatically used internally.

// Old way
key, _ := ecdsa.GenerateKey(elliptic.P256(), rand.Reader)

// New way: you can pass nil (a secure source is used automatically internally)
key, _ := ecdsa.GenerateKey(elliptic.P256(), nil)

4.3 Heap Base Address Randomization

On 64-bit platforms, the heap base address is now randomized, making memory address prediction harder. This increases defense against attacks when using cgo.

# Disable
GOEXPERIMENT=norandomizedheapbase64

4.4 Stronger TLS Security

• SecP256r1MLKEM768 and SecP384r1MLKEM1024 key exchanges are enabled by default
• Post-quantum hybrid TLS support

5.Tooling Improvements

5.1 go fix Rewritten

The go fix command has been completely rewritten on top of the Go analysis framework. It includes dozens of modernizers that automatically update code to take advantage of the latest language features.

# Update current code to the latest patterns
go fix ./...

//go:fix inline directive: A function call to a function annotated with the //go:fix inline directive is automatically inlined. This is useful when library authors want to automate API migrations.

// Add an inline directive to a deprecated function
//go:fix inline
func OldFunc() string {
	return NewFunc()
}

// When go fix runs, calls to OldFunc() are automatically converted to NewFunc()

5.2 go mod init Default Version Changed

When you run go mod init, the Go version is now set with compatibility against currently supported versions in mind. When run with Go 1.26, it is set to go 1.24.0.

6.Experimental Features

6.1 SIMD Operations (simd/archsimd)

A simd/archsimd package that supports architecture-specific vectorized operations has been added experimentally. On amd64, you can use 128/256/512-bit vector operations.

# Enable
GOEXPERIMENT=simd go build

// SIMD vector operation example (requires GOEXPERIMENT=simd)
va := archsimd.LoadFloat32x16Slice(a[i : i+16])
vb := archsimd.LoadFloat32x16Slice(b[i : i+16])
vSum := va.Add(vb)
vSum.StoreSlice(res[i : i+16])

6.2 Goroutine Leak Profile (goroutineleak)

A new profile that detects leaked goroutines has been added experimentally. It is scheduled to be enabled by default in Go 1.27.

# Enable
GOEXPERIMENT=goroutineleakprofile go build

# Access the endpoint
curl http://localhost:6060/debug/pprof/goroutineleak

Leak example: if an error occurs on an unbuffered channel and the function returns early, goroutines block forever.

func processWorkItems(ws []workItem) ([]workResult, error) {
	ch := make(chan result) // unbuffered channel
	for _, w := range ws {
		go func() {
			res, err := processWorkItem(w)
			ch <- result{res, err} // blocks → leak occurs
		}()
	}

	for range len(ws) {
		r := <-ch
		if r.err != nil {
			return nil, r.err // early return → remaining goroutines leak
		}
	}
	return results, nil
}

6.3 runtime/secret - Safely Erasing Sensitive Data

For the forward secrecy of cryptographic protocols, a runtime/secret package that safely erases sensitive data from memory has been added experimentally.

# Enable
GOEXPERIMENT=runtimesecret go build

// Example of automatically erasing sensitive data
secret.Do(func() {
	privKey, _ := ecdh.P256().GenerateKey(rand.Reader)
	sharedSecret, _ := privKey.ECDH(peerPublicKey)
	// ... session key negotiation
})
// The key is automatically deleted from memory when the function returns

7.Other Changes

7.1 Platform Changes

7.2 Other Standard Library Changes

8.Summary

Go 1.26 is a release with meaningful improvements across language expressiveness, performance, and security.

In particular, new(expr) and errors.AsType are features you can use immediately in everyday Go development, so adopt them actively. With Green Tea GC becoming the default, GC performance improves significantly without any extra configuration. The goroutine leak profile is experimental, but it is extremely useful for production debugging, so it is recommended to validate it in advance in a test environment.

Go 1.27 Preview

GODEBUG options scheduled for removal in Go 1.27:

• tlsunsafeekm, tlsrsakex, tls10server, tls3des
• x509keypairleaf, gotypesalias, asynctimerchan
• GOEXPERIMENT=nogreenteagc (disable option removed)

9.References

• Go 1.26 Release Notes
• Go 1.26 is released
• Go 1.26 변경사항 상세

When managing multiple applications with Helm Chart in a GitOps environment, manually creating an ArgoCD Application for each application is tedious and error-prone.

For example, suppose you have the following Helm Chart structure.

chart/
├── echo-server/
├── hello-world-server/
└── hello-world-server-hook/

How should you deploy these three applications with ArgoCD?

Deployment Patterns Provided by ArgoCD

In this article, we compare the App of Apps pattern and the ApplicationSet pattern with real examples.

Full sample code: kenshin579/argocd-charts-sample

2. Single Application

This is the most basic approach: you write a single Application YAML directly and deploy it.

# bootstrap/single-app/single.yaml
apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: hello-world-server
  namespace: argocd
spec:
  project: default
  source:
    repoURL: https://github.com/kenshin579/argocd-charts-sample
    path: chart/hello-world-server
    targetRevision: HEAD
    helm:
      valueFiles:
        - values.yaml
  destination:
    server: https://kubernetes.default.svc
    namespace: argocd-test

kubectl apply -f bootstrap/single-app/single.yaml -n argocd

This works fine when you only have a few applications, but as the number of managed targets grows, you have to write YAML files repeatedly, which makes maintenance harder.

3. App of Apps Pattern

3.1 Concept

This is a structure where a parent Application references a directory containing the child Application manifests. It can be implemented using only ArgoCD's built-in features.

bootstrap/app-of-apps/
├── apps.yaml                          # Parent Application
└── applications/
    ├── echo-server.yaml               # Child Application 1
    ├── hello-world-server.yaml        # Child Application 2
    └── hello-world-server-hook.yaml   # Child Application 3

3.2 Parent Application

The parent Application specifies the applications/ directory as source.path. ArgoCD automatically detects and creates all Application manifests inside this directory.

# bootstrap/app-of-apps/apps.yaml
apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: app-of-apps
  namespace: argocd
spec:
  project: default
  source:
    repoURL: https://github.com/kenshin579/argocd-charts-sample
    path: bootstrap/app-of-apps/applications
    targetRevision: HEAD
  destination:
    server: https://kubernetes.default.svc
    namespace: argocd
  syncPolicy:
    automated:
      prune: true
      selfHeal: true

3.3 Child Applications

Each child Application is defined as a separate YAML file that references an individual Helm Chart.

# bootstrap/app-of-apps/applications/echo-server.yaml
apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: echo-server
  namespace: argocd
spec:
  project: default
  source:
    repoURL: https://github.com/kenshin579/argocd-charts-sample
    path: chart/echo-server
    targetRevision: HEAD
    helm:
      valueFiles:
        - values.yaml
  destination:
    server: https://kubernetes.default.svc
    namespace: argocd-test
  syncPolicy:
    automated:
      prune: true
      selfHeal: true

# bootstrap/app-of-apps/applications/hello-world-server.yaml
apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: hello-world-server
  namespace: argocd
spec:
  project: default
  source:
    repoURL: https://github.com/kenshin579/argocd-charts-sample
    path: chart/hello-world-server
    targetRevision: HEAD
    helm:
      valueFiles:
        - values.yaml
  destination:
    server: https://kubernetes.default.svc
    namespace: argocd-test
  syncPolicy:
    automated:
      prune: true
      selfHeal: true

3.4 Deployment

kubectl apply -f bootstrap/app-of-apps/apps.yaml -n argocd

When you deploy the parent Application, ArgoCD reads the YAML files in the applications/ directory and automatically creates the child Applications.

3.5 Pros and Cons

Pros

• Simple concept and easy to understand
• Each Application can be controlled independently and in fine detail
• Easy to debug (you can immediately identify which Application has an issue)

Cons

• Requires writing a YAML file every time you add a new application
• The number of files to manage grows as the number of applications increases
• Duplicate code is easy to occur

4. ApplicationSet Pattern

4.1 Concept

ApplicationSet is an ArgoCD extension feature that dynamically generates Applications using a Generator (ArgoCD 2.0+). Being template-based, it lets you define multiple Applications at once and keep the DRY principle.

The main Generator types are as follows.

4.2 List Generator

Explicitly enumerate the list of applications to deploy. You can specify a name, path, namespace, and so on for each entry.

# bootstrap/application-set/appset-list.yaml
apiVersion: argoproj.io/v1alpha1
kind: ApplicationSet
metadata:
  name: chart-applications-list
  namespace: argocd
spec:
  generators:
    - list:
        elements:
          - name: echo-server
            path: chart/echo-server
            namespace: argocd-test
          - name: hello-world-server
            path: chart/hello-world-server
            namespace: argocd-test
          - name: hello-world-server-hook
            path: chart/hello-world-server-hook
            namespace: argocd-test
  template:
    metadata:
      name: '{{name}}'
    spec:
      project: default
      source:
        repoURL: https://github.com/kenshin579/argocd-charts-sample
        targetRevision: HEAD
        path: '{{path}}'
        helm:
          valueFiles:
            - values.yaml
      destination:
        server: https://kubernetes.default.svc
        namespace: '{{namespace}}'
      syncPolicy:
        automated:
          prune: true
          selfHeal: true
        syncOptions:
          - CreateNamespace=true

kubectl apply -f bootstrap/application-set/appset-list.yaml -n argocd

In the template block, the {{name}}, {{path}}, and {{namespace}} variables are substituted with each entry in generators.list.elements, creating the Applications.

4.3 Git Generator

This automatically detects the directory structure of a Git repository and creates Applications. When you add a new Chart directory, an Application is automatically created without any separate configuration change.

# bootstrap/application-set/appset.yaml
apiVersion: argoproj.io/v1alpha1
kind: ApplicationSet
metadata:
  name: chart-applications
  namespace: argocd
spec:
  generators:
    - git:
        repoURL: https://github.com/kenshin579/argocd-charts-sample
        revision: HEAD
        directories:
          - path: chart/*
  template:
    metadata:
      name: '{{path.basename}}'
    spec:
      project: default
      source:
        repoURL: https://github.com/kenshin579/argocd-charts-sample
        targetRevision: HEAD
        path: '{{path}}'
        helm:
          valueFiles:
            - values.yaml
      destination:
        server: https://kubernetes.default.svc
        namespace: argocd-test
      syncPolicy:
        automated:
          prune: true
          selfHeal: true
        syncOptions:
          - CreateNamespace=true

kubectl apply -f bootstrap/application-set/appset.yaml -n argocd

It detects all subdirectories under the chart/* path and uses {{path.basename}} (the directory name) as the Application name. Simply adding a chart/new-app/ directory automatically creates a new-app Application.

4.4 Matrix Generator

This combines multiple Generators to produce a cartesian product. It is useful for multi-environment (dev/staging/prod) deployments.

# bootstrap/application-set/appset-matrix.yaml
apiVersion: argoproj.io/v1alpha1
kind: ApplicationSet
metadata:
  name: chart-applications-matrix
  namespace: argocd
spec:
  generators:
    - matrix:
        generators:
          - git:
              repoURL: https://github.com/kenshin579/argocd-charts-sample
              revision: HEAD
              directories:
                - path: chart/*
          - list:
              elements:
                - env: dev
                  namespace: argocd-dev
                  replicas: "1"
                - env: staging
                  namespace: argocd-staging
                  replicas: "2"
                - env: prod
                  namespace: argocd-prod
                  replicas: "3"
  template:
    metadata:
      name: '{{path.basename}}-{{env}}'
    spec:
      project: default
      source:
        repoURL: https://github.com/kenshin579/argocd-charts-sample
        targetRevision: HEAD
        path: '{{path}}'
        helm:
          valueFiles:
            - values.yaml
          parameters:
            - name: replicaCount
              value: '{{replicas}}'
      destination:
        server: https://kubernetes.default.svc
        namespace: '{{namespace}}'
      syncPolicy:
        automated:
          prune: true
          selfHeal: true
        syncOptions:
          - CreateNamespace=true

kubectl apply -f bootstrap/application-set/appset-matrix.yaml -n argocd

3 Charts detected by the Git Generator × 3 environments from the List Generator = a total of 9 Applications are created.

• echo-server-dev, echo-server-staging, echo-server-prod
• hello-world-server-dev, hello-world-server-staging, hello-world-server-prod
• hello-world-server-hook-dev, hello-world-server-hook-staging, hello-world-server-hook-prod

Since you can set replicaCount differently per environment, you can deploy the same Chart tailored to each environment.

4.5 Pros and Cons

Pros

• Adheres to the DRY principle (minimizes duplicate code)
• Easy to add new applications (auto-detection when using Git Generator)
• Easy multi-environment deployment (Matrix Generator)

Cons

• Requires learning Generator and template syntax
• Debugging is relatively harder for complex requirements
• Because the same configuration applies to all Applications, it is unsuitable when each app needs completely different settings

5. App of Apps vs ApplicationSet Comparison

When to Use Which Pattern

When App of Apps Is a Good Fit

• Teams adopting ArgoCD for the first time
• When each Application needs completely different settings
• When there are few Applications and changes are infrequent

When ApplicationSet Is a Good Fit

• When you need to manage a large number of Applications
• When deploying the same app across multiple environments (dev/staging/prod)
• When new applications are added frequently
• When managing many services in a microservices architecture

6. FAQ

6.1 How do I delete a specific Application in an ApplicationSet?

If you directly delete an Application created by an ApplicationSet using the ArgoCD UI or kubectl delete, the ApplicationSet Controller detects this and recreates it.

The correct way to delete it is to remove the corresponding entry from the Generator.

Removing from a List Generator:

# Before
generators:
  - list:
      elements:
        - name: echo-server
          path: chart/echo-server
          namespace: argocd-test
        - name: hello-world-server
          path: chart/hello-world-server
          namespace: argocd-test

# After (echo-server removed)
generators:
  - list:
      elements:
        - name: hello-world-server
          path: chart/hello-world-server
          namespace: argocd-test

Excluding from a Git Generator:

generators:
  - git:
      repoURL: https://github.com/kenshin579/argocd-charts-sample
      revision: HEAD
      directories:
        - path: chart/*
        - path: chart/echo-server
          exclude: true  # exclude echo-server

6.2 How do I create a Secret needed by a PreSync Job first?

You can control the resource creation order using ArgoCD's Sync Wave. Resources with a lower Sync Wave value are created first.

Secret definition (sync-wave: "-1")

apiVersion: v1
kind: Secret
metadata:
  name: hello-world-server-hook-secret
  namespace: argocd-test
  annotations:
    argocd.argoproj.io/hook: PreSync
    argocd.argoproj.io/sync-wave: "-1"  # runs first
type: Opaque
data:
  common_secret.yaml: "dGVzdDoKICBkYXRhOgogICAgYXV0aF9rZXk6IC..."

PreSync Job definition (sync-wave: "1")

apiVersion: batch/v1
kind: Job
metadata:
  generateName: presync-job1
  annotations:
    argocd.argoproj.io/hook: PreSync
    argocd.argoproj.io/hook-delete-policy: BeforeHookCreation
    argocd.argoproj.io/sync-wave: "1"  # runs after the Secret
spec:
  backoffLimit: 2
  template:
    spec:
      volumes:
        - name: secret-volume
          secret:
            secretName: hello-world-server-hook-secret
      containers:
        - name: presync-job1
          image: busybox:1.36
          volumeMounts:
            - name: secret-volume
              mountPath: /opt/secret
          command:
            - /bin/sh
            - -c
            - |
              echo "Pre Sync Job - Secret available"
              cat /opt/secret/common_secret.yaml
      restartPolicy: Never

Sync Wave execution order:

sync-wave: "-1"  →  create Secret
sync-wave: "1"   →  run PreSync Job
(default: "0")   →  deploy normal resources (Deployment, Service, etc.)
PostSync         →  run PostSync Hook

Summary of key annotations:

7. Conclusion

We have looked at the two main patterns for managing multiple applications in ArgoCD.

• App of Apps: Intuitive and able to control each Application individually, making it suitable for small projects or the early stages of adopting ArgoCD.
• ApplicationSet: Template-based, reducing duplication with a high level of automation, making it suitable for large-scale microservices or multi-environment deployments.

The two patterns are not mutually exclusive, so you can choose the appropriate one or mix them based on your project's scale and requirements.

References

• ArgoCD ApplicationSet Documentation
• ArgoCD App of Apps Pattern
• ArgoCD Sync Waves and Hooks
• Example Repository - kenshin579/argocd-charts-sample

Ingress NGINX, one of the most widely used Ingress Controllers in Kubernetes environments, has announced its official end of life (EOL) as of March 2026.

End of support does not simply mean "no more updates."

• No more new feature development
• Possible discontinuation of security patches
• A gradual Deprecated position within the Kubernetes ecosystem

In other words, a structure that depends on Ingress NGINX over the long term becomes technical debt. As a result, transitioning to Gateway API—the next-generation standard proposed by the official Kubernetes SIG-Network—is becoming a necessity rather than a choice.

Note: What is being retired is the Ingress NGINX Controller (the implementation), while the Ingress API itself has been in GA status since Kubernetes 1.19 and has no Deprecated plan. That said, Gateway API is establishing itself as the next-generation standard.

This article covers the following topics.

• Limitations of the existing Ingress structure
• Concepts and core resources of Gateway API
• Migration strategy from Ingress to Gateway
• How to actually configure it using NGINX Gateway Fabric

The example code used in this article can be found in the GitHub repository.

2. Existing Ingress Structure and Its Limitations

Ingress is a resource for routing external traffic of a Kubernetes cluster to internal Services. It has long been used as a de facto standard thanks to the advantage of being able to define HTTP/HTTPS-based routing with simple YAML.

A basic Ingress resource is defined as follows. This configuration routes the example project's echo-server via Ingress.

# charts/ingress/ingress-routes/templates/ingress.yaml
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: echo-server-ingress
  annotations:
    nginx.ingress.kubernetes.io/rewrite-target: /
spec:
  ingressClassName: nginx
  rules:
    - host: echo.local
      http:
        paths:
          - path: /
            pathType: Prefix
            backend:
              service:
                name: echo-server
                port:
                  number: 80

However, Ingress has structural limitations.

2.1 Separation of Roles Is Difficult

A single Ingress resource mixes all of the following responsibilities.

• Infrastructure-level settings: LoadBalancer, TLS, IP policies
• Application-level routing: path and host based routing

This makes it difficult to separate the roles of the infrastructure team and the application team. Since a single resource must be modified by both sides, conflicts and confusion are likely to occur.

2.2 Limitations in Extensibility and Expressiveness

• TCP / UDP support is limited
• Advanced routing (header-based, weight-based, etc.) relies on Annotations
• Annotations differ across Controller implementations

As a result, the structure becomes one where the standard is loose while implementation dependency grows stronger. For example, an Annotation used in NGINX must be written differently in Traefik.

3. Ingress vs Gateway API Comparison

Gateway API emerged to solve these limitations of Ingress.

4. What Is Gateway API?

Gateway API is the next-generation API for standardizing the traffic ingress layer in Kubernetes. It is designed to replace Ingress and assumes extensibility and role separation from the ground up.

4.1 Core Resources

Gateway API separates and manages resources by role. This structure is similar to the StorageClass/PersistentVolume pattern.

GatewayClass

Defines which implementation to use. This is a resource managed by the infrastructure provider.

apiVersion: gateway.networking.k8s.io/v1
kind: GatewayClass
metadata:
  name: nginx
spec:
  controllerName: gateway.nginx.org/nginx-gateway-controller

• e.g., NGINX, Istio, Kong, Traefik, etc.

Gateway

The actual traffic ingress point. It handles LoadBalancer and Listener (TLS/HTTP) settings and is an infrastructure-perspective resource.

# charts/gateway/gateway-routes/templates/gateway.yaml
apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  name: echo-gateway
spec:
  gatewayClassName: nginx
  listeners:
    - name: http
      port: 80
      protocol: HTTP
      allowedRoutes:
        namespaces:
          from: All

If TLS is used, an HTTPS listener can be added.

    - name: https
      port: 443
      protocol: HTTPS
      allowedRoutes:
        namespaces:
          from: All
      tls:
        mode: Terminate
        certificateRefs:
          - kind: Secret
            name: echo-tls

HTTPRoute

Defines which Service a request should be sent to. This is an application-perspective resource.

# charts/gateway/gateway-routes/templates/httproutes.yaml
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: echo-server-route
spec:
  parentRefs:
    - name: echo-gateway
  hostnames:
    - echo.local
  rules:
    - matches:
        - path:
            type: PathPrefix
            value: /
      backendRefs:
        - name: echo-server
          namespace: app
          port: 80

Through this structure, the infrastructure settings (Gateway) and application routing (HTTPRoute) can be clearly separated.

4.2 Role-Based Design

Gateway API makes the separation of responsibilities between teams explicit.

4.3 Supported Route Types

Gateway API supports not only HTTP but also various protocols.

• HTTPRoute: HTTP/HTTPS traffic routing
• GRPCRoute: gRPC traffic routing
• TLSRoute: TLS passthrough routing
• TCPRoute: TCP traffic routing
• UDPRoute: UDP traffic routing

5. Types of Gateway API Implementations

Gateway API is only an interface; the actual behavior is handled by the implementation. Representative implementations are as follows.

This article explains things based on NGINX Gateway Fabric, the most natural choice for Ingress NGINX users.

6. Ingress → Gateway Migration Strategy

The transition from Ingress to Gateway is not a rip-and-replace approach all at once. A phased approach is important.

6.1 Analyzing the Existing Ingress Configuration

First, organize the Ingress currently in use.

• host / path rules
• TLS settings
• Whether Annotations are used
• Whether Controller-dependent features are used

In particular, Annotation-based features must be expressed differently in Gateway API.

6.2 Ingress ↔ HTTPRoute Mapping

The main elements of Ingress map to HTTPRoute as follows.

Comparing the example project's Ingress and HTTPRoute one-to-one looks like this.

Ingress approach:

# charts/ingress/ingress-routes/values.yaml
ingress:
  name: echo-server-ingress
  className: nginx
  annotations:
    nginx.ingress.kubernetes.io/rewrite-target: /
  hosts:
    - host: echo.local
      paths:
        - path: /
          pathType: Prefix
          serviceName: echo-server
          servicePort: 80

Gateway API approach:

# charts/gateway/gateway-routes/values.yaml
gateway:
  name: echo-gateway
  className: nginx
  listeners:
    - name: http
      port: 80
      protocol: HTTP
      allowedRoutes:
        from: All

httpRoutes:
  - name: echo-server-route
    hostnames:
      - echo.local
    rules:
      - matches:
          - path:
              type: PathPrefix
              value: /
        backendRefs:
          - name: echo-server
            namespace: app
            port: 80

Structurally, the Ingress → HTTPRoute conversion is relatively intuitive. The key difference is that in Gateway API, the infrastructure settings (Gateway) and routing rules (HTTPRoute) are separated.

Tip: Using AI coding tools such as Cursor or Claude Code, you can quickly convert existing Ingress YAML into the Gateway API format. Since the mapping rules are clear, the conversion accuracy is high, and batch conversion is possible even when there are many resources.

7. Configuring Gateway with NGINX Gateway Fabric

This section explains how to actually configure a Gateway based on the example project.

7.1 Architecture Overview

The example project has a structure that deploys Ingress and Gateway separately via ArgoCD on top of a Kind cluster. It provisions the Kind cluster and ArgoCD with Terraform, and ArgoCD deploys the Ingress or Gateway API resources and the echo-server application based on Helm charts. You can compare the differences by cross-deploying the Ingress approach and the Gateway approach against the same echo-server.

flowchart TD
    Terraform["Terraform"]
    Client["Client"]

    Terraform -->|Provisioning| Infra

    subgraph Kind_Cluster["Kind Cluster"]
        subgraph Infra["Infra (terraform/)"]
            KindCluster["Create Kind Cluster"]
            ArgoCD["Install ArgoCD"]
            KindCluster --> ArgoCD
        end

        subgraph Apps["Apps (charts/)"]
            Gateway["Ingress or Gateway API"]
            Echo["echo-server"]
        end

        ArgoCD -->|Deployment management| Gateway
        ArgoCD -->|Deployment management| Echo
        Gateway --> Echo
    end

    Client -->|HTTP request| Gateway

The project directory structure is as follows.

.
├── Makefile                    # Automation commands
├── terraform/                  # Kind cluster + ArgoCD installation
├── bootstrap/                  # ArgoCD Applications
│   ├── apps.yaml               # echo-server deployment
│   ├── infra-ingress.yaml      # Ingress infrastructure
│   └── infra-gateway.yaml      # Gateway infrastructure
└── charts/                     # Helm Charts
    ├── echo-server/            # Sample application
    ├── ingress/                # Ingress-related charts
    │   ├── nginx-ingress/      # NGINX Ingress Controller
    │   └── ingress-routes/     # Ingress resources
    └── gateway/                # Gateway API-related charts
        ├── gateway-api-crds/   # Gateway API CRDs
        ├── cert-manager/       # cert-manager (TLS certificate management)
        ├── nginx-gateway/      # NGINX Gateway Fabric
        └── gateway-routes/     # Gateway, HTTPRoute, TLS resources

To run the example, you need Terraform >= 1.0, kubectl, Docker, and Kind.

7.2 Creating the Cluster and Deploying Gateway

First, create a Kind cluster with Terraform and install ArgoCD.

make tf-init
make tf-apply

To deploy based on Gateway API, run the following command.

make deploy-gateway

This command applies the bootstrap/infra-gateway.yaml ArgoCD ApplicationSet to deploy the following components sequentially.

# bootstrap/infra-gateway.yaml
apiVersion: argoproj.io/v1alpha1
kind: ApplicationSet
metadata:
  name: gateway-infra
  namespace: argocd
spec:
  generators:
    - list:
        elements:
          - name: gateway-api-crds
            namespace: gateway
            path: cloud/ingress-gateway/charts/gateway/gateway-api-crds
          - name: nginx-gateway
            namespace: gateway
            path: cloud/ingress-gateway/charts/gateway/nginx-gateway
          - name: gateway-routes
            namespace: gateway
            path: cloud/ingress-gateway/charts/gateway/gateway-routes
  template:
    metadata:
      name: "{{name}}"
    spec:
      project: default
      source:
        repoURL: https://github.com/kenshin579/tutorials-go
        targetRevision: HEAD
        path: "{{path}}"
      destination:
        server: https://kubernetes.default.svc
        namespace: "{{namespace}}"
      syncPolicy:
        automated:
          prune: true
          selfHeal: true
        syncOptions:
          - CreateNamespace=true

The deployment flow is as follows.

1. Install Gateway API CRDs - Custom resource definitions such as Gateway, HTTPRoute, etc.
2. Install NGINX Gateway Fabric - The Gateway API implementation (Helm chart, version 2.2.1)
3. Deploy Gateway Routes - Create Gateway and HTTPRoute resources

7.3 Configuring Gateway Resources

To use Gateway API, you need to configure the implementation settings, define the actual routing resources, and, if necessary, set up TLS certificates. This section walks through, in order, from NGINX Gateway Fabric configuration to Gateway/HTTPRoute definitions and TLS settings.

7.3.1 NGINX Gateway Fabric Configuration

NGINX Gateway Fabric is installed via a Helm chart and is configured as follows to suit the Kind cluster environment.

# charts/gateway/nginx-gateway/values.yaml
nginx-gateway-fabric:
  service:
    type: NodePort
  nginxGateway:
    gwAPIExperimentalFeatures:
      enable: true
  nodeSelector:
    ingress-ready: "true"
  tolerations:
    - key: "node-role.kubernetes.io/control-plane"
      operator: "Equal"
      effect: "NoSchedule"
    - key: "node-role.kubernetes.io/master"
      operator: "Equal"
      effect: "NoSchedule"

• Expose the service with the NodePort type (Kind environment)
• Enabling gwAPIExperimentalFeatures allows the use of Gateway API experimental channel resources (TLSRoute, TCPRoute, UDPRoute, etc.)
• Configure tolerations so it can be scheduled on Control Plane nodes

7.3.2 Gateway and HTTPRoute

Gateway defines the traffic ingress point, and HTTPRoute defines the service routing rules. The example project manages them as Helm templates, so you can deploy them to suit various environments by modifying only the values file.

Gateway Resource

Gateway defines the ingress point where external traffic enters the cluster. It configures which GatewayClass to use, which port and protocol to listen on, and which namespaces' Routes to allow.

# charts/gateway/gateway-routes/templates/gateway.yaml
apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  name: {{ .Values.gateway.name }}
  namespace: {{ .Release.Namespace }}
spec:
  gatewayClassName: {{ .Values.gateway.className }}
  listeners:
    {{- range .Values.gateway.listeners }}
    - name: {{ .name }}
      port: {{ .port }}
      protocol: {{ .protocol }}
      {{- if .tls }}
      tls:
        mode: {{ .tls.mode }}
        certificateRefs:
          {{- range .tls.certificateRefs }}
          - kind: {{ .kind }}
            name: {{ .name }}
          {{- end }}
      {{- end }}
      allowedRoutes:
        namespaces:
          from: {{ .allowedRoutes.from }}
    {{- end }}

HTTPRoute Resource

HTTPRoute defines, based on hostname and path conditions, which backend Service to forward requests that come into the Gateway. Multiple HTTPRoutes can be connected to a single Gateway, enabling independent routing management per service.

# charts/gateway/gateway-routes/templates/httproutes.yaml
{{- range .Values.httpRoutes }}
---
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: {{ .name }}
  namespace: {{ $.Release.Namespace }}
spec:
  parentRefs:
    - name: {{ $.Values.gateway.name }}
      namespace: {{ $.Release.Namespace }}
  hostnames:
    {{- range .hostnames }}
    - {{ . }}
    {{- end }}
  rules:
    {{- range .rules }}
    - matches:
        {{- range .matches }}
        - path:
            type: {{ .path.type }}
            value: {{ .path.value }}
        {{- end }}
      backendRefs:
        {{- range .backendRefs }}
        - name: {{ .name }}
          namespace: {{ .namespace }}
          port: {{ .port }}
        {{- end }}
    {{- end }}
{{- end }}

When rendered with the actual values file, the following resources are created.

# Gateway: echo-gateway (port 80, HTTP)
# HTTPRoute: echo-server-route
#   - host: echo.local
#   - path: / (PathPrefix)
#   - backend: echo-server (namespace: app, port: 80)

7.3.3 TLS/HTTPS Configuration (Optional)

To use HTTPS, enable cert-manager and add the related settings.

Step 1: Enable cert-manager

Uncomment the cert-manager entry in bootstrap/infra-gateway.yaml.

elements:
  - name: gateway-api-crds
    namespace: gateway
    path: cloud/ingress-gateway/charts/gateway/gateway-api-crds
  - name: cert-manager      # Uncomment
    namespace: gateway
    path: cloud/ingress-gateway/charts/gateway/cert-manager
  - name: nginx-gateway
    namespace: gateway
    path: cloud/ingress-gateway/charts/gateway/nginx-gateway
  - name: gateway-routes
    namespace: gateway
    path: cloud/ingress-gateway/charts/gateway/gateway-routes

Step 2: Configure TLS-related values

Enable TLS in charts/gateway/gateway-routes/values.yaml.

tls:
  enabled: true  # change from false -> true

gateway:
  listeners:
    - name: http
      port: 80
      protocol: HTTP
      allowedRoutes:
        from: All
    - name: https        # Uncomment
      port: 443
      protocol: HTTPS
      allowedRoutes:
        from: All
      tls:
        mode: Terminate
        certificateRefs:
          - kind: Secret
            name: echo-tls

letsencrypt:
  email: your-email@example.com
  environment: staging  # staging or prod

certificate:
  name: echo-tls
  dnsNames:
    - echo.local

When TLS is enabled, the following resources are additionally created.

ClusterIssuer is a resource that defines the CA (Certificate Authority) from which cert-manager issues certificates. It is shared across the entire cluster, and the example below uses the Let's Encrypt ACME server.

# charts/gateway/gateway-routes/templates/clusterissuer.yaml
apiVersion: cert-manager.io/v1
kind: ClusterIssuer
metadata:
  name: letsencrypt-staging
spec:
  acme:
    email: your-email@example.com
    server: https://acme-staging-v02.api.letsencrypt.org/directory
    privateKeySecretRef:
      name: letsencrypt-staging-key
    solvers:
      - http01:
          gatewayHTTPRoute:
            parentRefs:
              - name: echo-gateway
                kind: Gateway

Certificate is a resource that requests the actual issuance of a TLS certificate. The issued certificate is stored in the specified Secret and is referenced by the Gateway's TLS listener.

# charts/gateway/gateway-routes/templates/certificate.yaml
apiVersion: cert-manager.io/v1
kind: Certificate
metadata:
  name: echo-tls
spec:
  secretName: echo-tls
  dnsNames:
    - echo.local
  issuerRef:
    name: letsencrypt-staging
    kind: ClusterIssuer

7.4 Testing

Once the deployment is complete, verify the behavior with the following commands.

# Gateway test
make test-gateway

# Direct curl call
curl -H "Host: echo.local" http://localhost/ping

7.5 Comparative Deployment with the Ingress Approach

To deploy the same echo-server using the Ingress approach, use the following command.

make deploy-ingress

In this case, bootstrap/infra-ingress.yaml is applied, deploying the NGINX Ingress Controller and the Ingress resource. You can directly compare the differences by cross-deploying the two approaches.

8. Conclusion

The end of support for Ingress NGINX may look like an issue that still has time left. However, an infrastructure transition is the kind of task that requires the most time for preparation.

• For a simple service, there is no need to remove Ingress right away
• However, for a new service or a long-term operational service, it is reasonable to consider transitioning to Gateway API
• In particular, for Ingress NGINX users, NGINX Gateway Fabric is the most natural choice
• Since Ingress and Gateway can coexist, a phased transition is possible

Gateway API is not merely a replacement for Ingress, but a standard that redefines the structure of the Kubernetes network layer.

9. References

• Ingress NGINX End of Support Notice
• Gateway API Overview - 요즘IT
• Gateway API Hands-on Notes - somaz
• Gateway API Hands-on Notes - chabin
• Gateway API Official Docs
• NGINX Gateway Fabric GitHub
• Example Code Repository

OpenClaw is a self-hosted gateway that connects messaging apps such as WhatsApp, Telegram, and Discord to AI agents. By default a single agent handles all messages, but in real-world operations you often want to separate bots by purpose.

For example:

• Alert bot: delivers only server failure or deployment notifications
• Monitoring bot: analyzes system metrics and produces reports
• Assistant bot: handles everyday questions and tasks

OpenClaw's multi-agent feature makes this kind of setup possible. Each agent runs as a completely isolated, independent "brain" and can be managed from a single Gateway.

This article walks through how to configure multiple Telegram bots as OpenClaw multi-agents, step by step. The whole process proceeds in the following four steps.

1. Create Telegram bots - Create as many bots as agents in BotFather
2. Add agents - Register agents with the OpenClaw CLI
3. Pass bot tokens - Hand the tokens to OpenClaw to auto-configure the bindings
4. Verify and run - Check the agent list and channel status

For OpenClaw's basic concepts and installation, refer to the Complete OpenClaw Guide article.

2. Multi-Agent Architecture

2.1 Overall Structure

The core of a multi-agent system is that a single Gateway manages multiple agents and routes messages according to binding rules.

flowchart LR
    subgraph Telegram
        B1["🤖 alerts_bot"]
        B2["🤖 monitoring_bot"]
        B3["🤖 assistant_bot"]
    end

    subgraph Gateway
        R["Routing Engine\n(Bindings)"]
    end

    subgraph Agents
        A1["Agent: alerts\n(Claude Opus)"]
        A2["Agent: monitoring\n(Claude Sonnet)"]
        A3["Agent: assistant\n(Claude Haiku)"]
    end

    B1 --> R
    B2 --> R
    B3 --> R
    R --> A1
    R --> A2
    R --> A3

Each Telegram bot has an independent account (accountId) and is connected to a specific agent through binding rules.

2.2 Components of an Agent

Each agent has completely isolated components.

Caution: never share the agentDir between agents. Sharing it causes authentication conflicts.

2.3 Directory Structure

The actual multi-agent structure on the filesystem looks like this.

graph TD
    ROOT["~/.openclaw/"] --> CONFIG["openclaw.json"]
    ROOT --> WS1["workspace-alerts/"]
    ROOT --> WS2["workspace-monitoring/"]
    ROOT --> AGENTS["agents/"]

    WS1 --> WS1_A["AGENTS.md"]
    WS1 --> WS1_S["SOUL.md"]
    WS1 --> WS1_U["USER.md"]

    WS2 --> WS2_A["AGENTS.md"]
    WS2 --> WS2_S["SOUL.md"]
    WS2 --> WS2_U["USER.md"]

    AGENTS --> AG1["alerts/"]
    AGENTS --> AG2["monitoring/"]

    AG1 --> AG1_D["agent/"]
    AG1 --> AG1_S["sessions/"]
    AG1_D --> AG1_AUTH["auth-profiles.json"]

    AG2 --> AG2_D["agent/"]
    AG2 --> AG2_S["sessions/"]
    AG2_D --> AG2_AUTH["auth-profiles.json"]

Each agent's Workspace contains files that define the agent's character and role.

• AGENTS.md: the agent's instructions and tool settings
• SOUL.md: the agent's persona and personality
• USER.md: user information and preferences

3. Multi-Agent Configuration

3.1 Step 1 - Create Telegram Bots (BotFather)

In Telegram, chat with @BotFather and create as many bots as you have agents.

1. Send the /newbot command to BotFather
2. Enter the bot name (e.g., My Alert Bot)
3. Enter the bot username (e.g., my_alert_bot)
4. Store the issued bot token securely

Repeat this process for the number of bots you need. For example, if you plan to run three agents, create three bots.

# Example tokens received from BotFather
alerts_bot:     123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11
monitoring_bot: 987654:XYZ-UVW9876tgHjk-abc34V3w9z456ty22
assistant_bot:  111222:GHI-JKL5678mnOpq-rst12X4y6z789ab33

3.2 Step 2 - Add Agents

Add each agent with the OpenClaw CLI.

openclaw agents add alerts
openclaw agents add monitoring
openclaw agents add assistant

Each command automatically creates the following.

• Workspace directory (~/.openclaw/workspace-<agentId>/)
• State directory (~/.openclaw/agents/<agentId>/agent/)
• Session store (~/.openclaw/agents/<agentId>/sessions/)

When you actually run openclaw agents add, an interactive wizard runs.

$ openclaw agents add proj-photo

🦞 OpenClaw 2026.2.17 (4134875) — The UNIX philosophy meets your DMs.

┌  Add OpenClaw agent
│
◇  Workspace directory
│  /Users/user/.openclaw/workspace-proj-photo
│
◇  Copy auth profiles from "main"?
│  Yes
│
◇  Auth profiles ─────────────────────╮
│                                     │
│  Copied auth profiles from "main".  │
│                                     │
├─────────────────────────────────────╯
│
◇  Configure model/auth for this agent now?
│  Yes
│
◇  Model/auth provider
│  Anthropic
│
◇  Anthropic auth method
│  Anthropic token (paste setup-token)
│
◇  Paste Anthropic setup-token
│  sk-ant-oat01-****
│
◇  Token name (blank = default)
│  proj-photo
│
◇  Configure chat channels now?
│  Yes
│
◇  Select a channel
│  Finished
│
└  Agent "proj-photo" ready.

Workspace, auth profiles, and model settings are all completed in one go.

3.3 Step 3 - Pass the Bot Tokens to OpenClaw

You don't need to edit openclaw.json directly. In the OpenClaw chat window (Dashboard or Telegram), tell it that you added a new bot and hand over the token; OpenClaw will add the configuration on its own and restart the Gateway.

User: "I added a new Telegram bot. Its name is alerts_bot and the token is 123456:ABC-DEF1234..."
OpenClaw: Configuration added → Gateway automatically restarted

Actual workflow:

1. Create a bot in BotFather → copy the token
2. Pass the token in the OpenClaw chat window
3. OpenClaw handles it automatically:
   • Adds the agent and Telegram account to openclaw.json
   • Creates binding rules
   • Restarts the Gateway

Below is what passing a bot token actually looks like in the OpenClaw Telegram chat window. Once you hand over the token, OpenClaw automatically adds the configuration and shows the bot status.

3.4 Understanding the openclaw.json Structure

OpenClaw generates the configuration automatically, but understanding the internal structure helps with customization and troubleshooting. openclaw.json consists of three main sections.

agents Section

Defines each agent (AI brain). You can assign an independent workspace and model to each agent.

{
  agents: {
    list: [
      {
        id: "alerts",
        name: "Alert Agent",
        workspace: "~/.openclaw/workspace-alerts",
        agentDir: "~/.openclaw/agents/alerts/agent",
        model: "anthropic/claude-opus-4-6",
      },
      {
        id: "monitoring",
        name: "Monitoring Agent",
        workspace: "~/.openclaw/workspace-monitoring",
        agentDir: "~/.openclaw/agents/monitoring/agent",
        model: "anthropic/claude-sonnet-4-5",
      },
      {
        id: "assistant",
        name: "Assistant Agent",
        workspace: "~/.openclaw/workspace-assistant",
        agentDir: "~/.openclaw/agents/assistant/agent",
        model: "anthropic/claude-haiku-4-5",
      },
    ],
  },
}

Since each agent can use a different model, you can tune performance and cost to fit each purpose.

channels Section

Configures Telegram bot tokens and access policies.

{
  channels: {
    telegram: {
      accounts: {
        alerts_bot: {
          botToken: "123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11",
          dmPolicy: "pairing",
        },
        monitoring_bot: {
          botToken: "987654:XYZ-UVW9876tgHjk-abc34V3w9z456ty22",
          dmPolicy: "allowlist",
          allowFrom: ["tg:123456789"],
        },
        assistant_bot: {
          botToken: "111222:GHI-JKL5678mnOpq-rst12X4y6z789ab33",
          dmPolicy: "open",
          allowFrom: ["*"],
        },
      },
    },
  },
}

dmPolicy controls who can send DMs to a bot.

bindings Section

Defines the routing rules for which bot's messages go to which agent.

{
  bindings: [
    {
      agentId: "alerts",
      match: { channel: "telegram", accountId: "alerts_bot" },
    },
    {
      agentId: "monitoring",
      match: { channel: "telegram", accountId: "monitoring_bot" },
    },
    {
      agentId: "assistant",
      match: { channel: "telegram", accountId: "assistant_bot" },
    },
  ],
}

When you need advanced settings such as changing dmPolicy, swapping models, or refining bindings, you can edit this file directly.

3.5 Step 4 - Verify and Run

Once the configuration is complete, verify it with the following commands.

# Check the agent list and bindings
openclaw agents list --bindings

# Check channel status (verify bot token validity)
openclaw channels status --probe

# Restart the Gateway (when changing settings manually)
openclaw gateway restart

If everything is set up correctly, sending a message to each Telegram bot will get a response from the corresponding agent. Below is what an actual conversation with a newly added bot looks like.

4. Conclusion

With OpenClaw's multi-agent feature, you can run multiple Telegram bots independently from a single Gateway. To summarize the key points:

• Each agent is an independent AI brain with completely isolated Workspace, agentDir, and sessions
• Create bots in BotFather and just hand the tokens to OpenClaw for automatic configuration
• Binding rules route messages to agents, allowing branching per bot, per user, or per group
• Use a different AI model per agent to optimize performance and cost

Multi-agent isn't just about creating several bots; it's about giving each bot a specialized role and context. A well-designed agent separation raises both response quality and operational efficiency at the same time.

5. References

• OpenClaw Official Documentation
• Multi-Agent Concept
• Telegram Channel Setup
• Getting Started Guide

Connecting Google Workspace to OpenClaw lets you control Gmail, Calendar, and Drive entirely through Telegram chat. This article walks through setting up gog (Google Workspace CLI) in OpenClaw.

After downloading the OAuth JSON file from the Google Cloud Console, every step was carried out solely through Telegram chat. I never typed a command directly in a terminal.

• OAuth setup in the Google Cloud Console (web browser)
• After sending the JSON credential file to Telegram, everything was done through Telegram, without typing any CLI command directly

For the basic OpenClaw installation and Telegram bot integration, see the Complete OpenClaw Guide.

2. What is gog?

gog is a CLI tool for controlling Google Workspace from the terminal.

Supported services:

• Gmail - search, read, send mail, and manage labels
• Calendar - view, create, and edit events
• Drive - search, upload, and download files
• Contacts - manage contacts
• Docs / Sheets / Slides - manage documents
• Tasks - manage to-dos
• Chat - Google Chat messages
• Forms - query survey data
• Apps Script - manage scripts

By integrating with OpenClaw, you can handle all of this through natural-language conversation.

flowchart LR
    A[User] -->|Telegram message| B[OpenClaw Bot]
    B -->|Run gog CLI| C[gog]
    C -->|OAuth 2.0| D[Google Workspace API]
    D --> E[Gmail]
    D --> F[Calendar]
    D --> G[Drive]
    D --> H[Docs / Sheets / ...]

3. Prerequisites

• OpenClaw installed and Telegram bot integration complete
• macOS environment (brew available)
• A Google account

4. Full Setup Flow

The overall flow can be summarized as follows.

1. Google Cloud Console - create an OAuth project & a Client ID → download JSON
2. Telegram - send the JSON file to the OpenClaw bot
3. Telegram - provide your Gmail address → OpenClaw generates an authentication URL
4. Browser - sign in to Google & approve permissions → copy the callback URL
5. Telegram - paste the callback URL → OpenClaw exchanges the token & finishes the setup
6. Google Cloud Console - enable the Gmail, Calendar, and Drive APIs
7. Telegram - "Tell me tomorrow's schedule" → start using Google Workspace

5. Installing gog

I asked the OpenClaw bot in Telegram how to set up gog.

Me: I want to set up gog google workspace. https://clawhub.ai/steipete/gog

OpenClaw: I already installed gogcli earlier. Now we need to set up Google authentication. Let's go step by step:

Step 1: Create a Google Cloud OAuth client

1. Open the Google Cloud Console — https://console.cloud.google.com/
2. Create a new project (name: gog-cli)
3. Configure APIs & Services → OAuth consent screen
4. APIs & Services → Credentials → Create Credentials → OAuth client ID
   • Application type: Desktop app
   • Download client_secret_xxxx.json

OpenClaw immediately guides you through the entire setup. If gog is not yet installed, just say "install gog" and OpenClaw runs brew install gogcli in the background.

6. Google Cloud Console OAuth Setup

This is the only stage that the user must perform directly in a web browser.

6.1 Create a Project

Go to the Google Cloud Console and create a new project.

• Project name: gog-cli (any name you like)

6.2 Configure the OAuth Consent Screen

Click APIs & Services → OAuth consent screen to go to the OAuth overview page, then click the Get Started button.

Enter the app information:

• App name: gog-cli
• User support email: your own email

Select the audience:

• Select External

Enter the contact information and finish.

## 6.3 Create an OAuth Client ID

Go to APIs & Services → Credentials → Create Credentials → OAuth client ID.

• Application type: Desktop app
• Name: gog-cli
• Click Create

Once it is created, click the Download JSON button to download the client_secret_xxxx...xxxx.json file.

This is the last step you do in a web browser. From here on, you return to Telegram chat.

7. gog Authentication Setup (done via Telegram chat)

From this section on, you do not operate the terminal directly. OpenClaw runs every CLI command on your behalf.

7.1 Send the JSON Credential File

Send the downloaded JSON file to the Telegram chat as a file attachment.

Me: (attaching the client_secret_xxxx...xxxx.json file)

OpenClaw: Got the file! I'll proceed with the setup.

OpenClaw: Credential registration complete! Now we need to authenticate the Google account. Tell me your Gmail address — I'll run it in --manual mode and send you the authentication URL!

OpenClaw background tasks:

# 1. Save the JSON file received from Telegram to the Mac Mini
mv /tmp/telegram_download/client_secret_xxxx.json ~/Downloads/

# 2. Register the OAuth credentials with gog
gog auth credentials ~/Downloads/client_secret_xxxx...xxxx.json

7.2 Provide the Gmail Address → Receive the Authentication URL

Type your Gmail address into the chat, and OpenClaw sends you the authentication URL.

Me: your-email...@gmail.com

OpenClaw: Standing by! Now follow the steps below:

1. Open this link in your browser: https://accounts.google.com/o/oauth2/auth?access_type=offline&client_id=xxxx...xxxx&...

2. Sign in to Google and approve the permissions

3. It's normal for the page not to open! Copy the full URL from the browser's address bar and send it to me It's a URL that looks like http://127.0.0.1:.../oauth2/callback?state=...&code=...!

OpenClaw background tasks:

# Start authentication in --manual mode (print the URL directly instead of opening a browser)
gog auth add your-email...@gmail.com --manual

# Send the printed OAuth authentication URL as a Telegram message
# Wait for the local callback server (127.0.0.1:50554) in the background

7.3 Troubleshooting: 403 access_denied

When you first open the authentication URL, you may get a 403 error.

Me: (sending the 403 access_denied screenshot)

OpenClaw: 403 access_denied — it's because the OAuth app is still in test mode. You need to add a test user.

In the Google Cloud Console:

1. Go to APIs & Services → OAuth consent screen
2. In the Test users section, click Add users
3. Add your own email

Me: I don't want to add a test user; I just want it to actually work. Can I just click Publish app?

OpenClaw: Yes, you can Publish the app! If only you use it, there's no problem.

Me: Done publishing.

The cause is that OAuth apps are created in test mode by default. There are two ways to fix it:

1. Publish the app: OAuth consent screen → Audience → click Publish app (recommended if only you use it)
2. Add a test user: Audience → add your own email to the test users

7.4 Sign in to Google → Provide the callback URL

After publishing the app, open the authentication URL again and the Google sign-in proceeds normally.

1. Select an account

2. "Google hasn't verified this app" warning

A warning appears because the app hasn't gone through Google's official verification. Since you created the app yourself, click Advanced → Continue.

3. Approve the permission request

The list of Google services that gog-cli will access is displayed. Click Continue to approve all permissions.

4. Copy the callback URL

After approval, you are redirected to a http://127.0.0.1:50554/oauth2/callback?... address, and it is normal for the page not to open. Copy the full URL from the browser's address bar and paste it into Telegram.

Me: http://127.0.0.1:50554/oauth2/callback?state=xxxx...xxxx&code=4/0Axxxx...xxxx&scope=email%20profile%20...

OpenClaw: Authentication complete!

email     your-email...@gmail.com
services  appscript, calendar, chat, classroom, contacts,
          docs, drive, forms, gmail, people, sheets, slides, tasks

OpenClaw background tasks:

# 1. Extract the authorization code from the callback URL the user sent
#    http://127.0.0.1:50554/oauth2/callback?code=4/0Axxxx...xxxx&...
#    → code = "4/0Axxxx...xxxx"

# 2. Exchange the authorization code for Google OAuth tokens
#    (internally gog exchanges code → access_token + refresh_token)

# 3. Store the tokens securely in the macOS Keychain

# 4. Verify the authentication result
gog auth list
# → email: your-email...@gmail.com, confirm 13 services connected

7.5 Troubleshooting: macOS Keychain Access

gog stores authentication tokens in the macOS Keychain. On the first run, a Keychain access prompt may appear.

OpenClaw: gog auth list keeps hanging — it might be a macOS Keychain access issue. Test it directly in the terminal on the Mac Mini — a Keychain access prompt may appear.

Me: A lot of Keychain access prompt windows popped up; I entered my login password and finished.

OpenClaw: Great! Now that you've allowed Keychain access, it should work. Let me test again!

The Keychain prompt must be handled directly on the Mac Mini screen. Once allowed, it is accessed automatically thereafter.

7.6 Set the Environment Variable

You need to set the GOG_ACCOUNT environment variable so you don't have to add the --account option every time.

Me: Is the GOG_ACCOUNT environment variable set as well?

OpenClaw: It's not! I'll set it up.

OpenClaw: Done adding it!

• Added export GOG_ACCOUNT=your-email...@gmail.com to ~/.zshrc
• Applied automatically from new terminal sessions

Me: Run source ~/.zshrc.

OpenClaw: Done! GOG_ACCOUNT=your-email...@gmail.com is now applied.

OpenClaw background tasks:

# 1. Add the environment variable to ~/.zshrc
echo 'export GOG_ACCOUNT=your-email...@gmail.com' >> ~/.zshrc

# 2. Apply it to the current session
source ~/.zshrc

8. Enabling Google APIs

Authentication is complete, but you must enable the APIs you actually use in the Google Cloud project for them to work. As OpenClaw tries testing, it tells you the list of required APIs and their links.

OpenClaw: We're making progress! Keychain is resolved, and now we need to enable the APIs in Google Cloud.

1. Gmail API: https://console.developers.google.com/apis/api/gmail.googleapis.com/...
2. Calendar API: https://console.developers.google.com/apis/api/calendar-json.googleapis.com/...
3. Drive API: https://console.developers.google.com/apis/api/drive.googleapis.com/...

In the Google Cloud Console, search for each API and click the Enable button.

Once you let OpenClaw know in Telegram that it's enabled, OpenClaw tests it right away.

OpenClaw background tasks:

# Run the test as soon as the user says "I enabled it"
gog gmail search 'newer_than:1d'     # → confirm Gmail API works
gog calendar calendars                # → confirm Calendar API works
gog drive files list                  # → confirm Drive API works

# Summarize the results and respond via Telegram

You can enable additional APIs such as Contacts, Tasks, and Sheets as needed.

9. Real-World Usage

Once the setup is complete, you can use Google Workspace right away with natural language.

9.1 Querying Calendar Events

9.2 Natural Language → gog Command Conversion

When the user makes a request in natural language, OpenClaw converts it into the appropriate gog command and runs it. The user doesn't need to know the gog command syntax at all.

10. Wrapping Up

The entire setup takes about 10 minutes, and the only parts the user does directly are the Google Cloud Console and the browser authentication.

After setup, you just make requests in natural language from Telegram. Say things like "Check my mail today" or "Tell me this week's schedule," and OpenClaw picks the right gog command on its own and answers with the results organized in a human-readable form.

11. References

• gog official docs (ClaWHub)
• Google Cloud Console
• Complete OpenClaw Guide
• Setting Up OpenClaw Telegram Multi-Agent

One of our teammates built an internal debugging tool with Wails. It turned out so clean, and it was built in Golang — which we're already comfortable with — that I thought this would be a good opportunity to study Wails and write it up on the blog.

Building web servers or CLI tools in Go is familiar, but what about desktop apps? Wails is a framework that lets you build cross-platform desktop applications by combining a Go backend with a web frontend (React, Vue, Svelte, etc.).

Unlike Electron, which bundles Chromium, it uses the OS's native WebView, so the binary size is small and memory usage is low. What's appealing is that you can build native-level desktop apps while leveraging the web technologies Go developers already know.

In this article, we'll build a Todo app with Wails v2, covering the whole process — from project creation to Go-JavaScript binding, using native features, and building.

The full example code is available on GitHub.

1. Introduction

1.1 What Is Wails?

Wails is a framework that lets you build desktop apps in Go. The core idea is simple:

• Backend: write business logic in Go
• Frontend: write the UI with web technologies such as React, Vue, Svelte
• Binding: call Go methods directly from JavaScript

The Go code and the web frontend are compiled into a single single binary, and the frontend assets are embedded into the binary with go:embed.

1.2 Comparison with Electron and Tauri

When choosing a desktop app framework, you often end up comparing Wails, Electron, and Tauri.