This post assumes several accounts are already available for Claude Code or Codex, and multiple people want to share those accounts' unused capacity. One person might manage several accounts, or several people might contribute accounts to a shared pool. Each user does not need to own multiple accounts. The pool they can use needs to contain more than one.

For example, suppose three people share Claude Code accounts A, B, and C. One person has nearly exhausted A's allowance during a long task, while B and C still have capacity. Instead of checking each account and manually changing logins every time, a server selects an account with room left and assigns it to the person who needs it.

Claude Code needs a pool of Claude Code accounts, and Codex needs a pool of Codex accounts. If you use only one tool, you only need accounts for that tool. A Claude Code account and a Codex account cannot exchange their unused allowances.

Each account's usage limits still apply. People assigned the same account share that account's allowance. Connecting one account to several computers does not increase its limit, and once every account in the pool has reached its limit, there is no spare capacity left to assign. The purpose of this setup is to make use of unused capacity across accounts that are already available.

A server that registers the accounts, checks their status, and assigns credentials must also be in place. I call this the credential server throughout this post. Users receive credentials for the account it selects and run the tool on their own computers. As usage accumulates, the server prepares credentials for another account with capacity available.

The rest of this post assumes that credential server already exists and explains how to connect shared accounts on a personal computer. I normally work with my own subscription account and switch to a shared account when needed. The setup keeps the two accounts' logins and histories separate, passes credentials only to the process that needs them, and prepares credentials for the next launch. I also cover how to apply a different account to a session that is already running.

Where the two tools read credentials

At startup, Claude Code checks several credential sources in a defined order. For the sources relevant to this setup, shell variables such as ANTHROPIC_AUTH_TOKEN or ANTHROPIC_API_KEY take precedence. Next comes CLAUDE_CODE_OAUTH_TOKEN, which holds a subscription token, followed by the login saved through /login. I pass the shared account's token through CLAUDE_CODE_OAUTH_TOKEN. If the first two variables remain in the shell, they take precedence over it, so I clear them. Claude Code authentication documentation

Logins are stored separately for each configuration directory. The default is ~/.claude, and CLAUDE_CONFIG_DIR changes it. On macOS, login credentials are stored in Keychain. A different configuration directory also gets its own associated Keychain entry.

For Codex, codex login creates the auth.json file used for authentication. The file lives under CODEX_HOME, which defaults to ~/.codex. The CLI, IDE extension, and desktop app share this login. Depending on the configuration, credentials can also be stored in the operating system's credential store; this post uses file storage. Codex authentication documentation

Both tools select their credentials when a session starts and continue using that account for the session. A configuration directory can hold only one account at a time; using two accounts in the same directory can overwrite login state and history. The rest of the setup follows from these two constraints.

Connecting shared accounts on each computer

The setup has four parts. The diagram shows Claude Code; I explain the differences for Codex below.

1. Two configuration directories. My own account uses the default directory, while the shared account uses a dedicated one. Only settings that define how I work are shared through symbolic links.
2. A shared-account launcher. This is a shell function. At launch, it fetches the latest token from the credential server, selects the dedicated directory, and passes the token only to that invocation. Running plain claude still uses my own account.
3. Keychain. It stores the key used to access the credential server and a copy of the most recently received token. There are no plaintext files for those values.
4. A rotation worker. This is a shell script kept running by launchd. Every 10 minutes, it checks the current token's status. When the account is approaching its limit, it fetches a new token and replaces the cached copy.

Codex follows the same pattern. Its rotation worker updates auth.json in the dedicated directory instead of Keychain, and its launcher simply points CODEX_HOME at that directory.

Separate accounts by directory and share settings through links

Pointing CLAUDE_CONFIG_DIR at a new directory immediately separates the account. However, Claude Code uses that directory for both authentication and configuration. Starting with an empty directory means no plugins, skills, commands, or hooks: it looks like a fresh installation. I therefore separate account-specific data from working preferences, then link only the latter back to the default directory. Changing the directory also moves ~/.claude.json to .claude.json inside the new directory. Claude Code directory documentation

The two accounts keep separate conversation histories. A conversation started with the shared account cannot be resumed from my personal account with --resume. Personal MCP servers must also be registered separately in the dedicated directory. Linked settings, however, stay shared: a change made from either side applies to both.

One detail can break those links. When an application writes settings to a temporary file and renames it into place, it may replace the symbolic link itself with a regular file instead of updating the link's target. After that, the two directories' settings drift apart. I encountered this with settings.json. If a change on one side does not appear on the other, first check whether the entry in the dedicated directory is still a symbolic link.

The first-run screens in a new directory

Handling the first-run screens took the most time in this setup. A new directory has no onboarding state, so the first interactive launch shows theme and login-method selection screens. These are separate from token authentication, which makes the situation confusing: claude -p can work perfectly. If I casually log in at that point, my personal login gets saved in the dedicated directory. From then on, even the shared-account launcher connects to my own account.

To avoid that, I copy only the markers indicating completed onboarding from the default directory's .claude.json into the dedicated one. Copying hasCompletedOnboarding alone did not suppress the theme screen. Several onboarding-related keys were needed. I identified them by capturing and comparing the first-run screens in a pseudo-terminal. I do not copy oauthAccount, because it carries account identity with it.

The lesson was to test interactive mode separately even when -p works. After changing the setup, I open an interactive session and run /status to see which authentication is in use. A shared token appears as CLAUDE_CODE_OAUTH_TOKEN; my own account shows the login method and email address. If the login selection screen still appears, I exit without choosing anything.

Three directories for Codex

Codex uses CODEX_HOME for the same purpose. I split it into three directories.

I link config.toml, AGENTS.md, skills, and hooks to the default directory. Each directory keeps its own auth.json, sessions, history, and state database. Multiple processes writing to the same state database can corrupt it.

The main reason I separated Codex directories was the trouble caused by logging out. In this shared-account setup, running codex logout or codex login while connected to the shared account removes the local file and invalidates credentials on the provider side. Other people and devices using the same credentials can be disconnected too. Keeping the shared account in the default directory makes it easy to log out by habit and disrupt everyone else. A dedicated directory means plain codex acts on my own account instead. To remove only the local shared credentials, I delete that directory's auth.json rather than logging out. The rotation worker restores it within 10 minutes.

Pass credentials only to the process being launched

The simplest way to use a shared token is to set CLAUDE_CODE_OAUTH_TOKEN and CLAUDE_CONFIG_DIR globally in a shell startup file. That convenience creates two problems. Because the environment variable takes precedence over the saved login, plain claude connects to the shared account instead of my own. Other processes launched from that shell, including editors, also inherit the token. I avoid passing tokens as command-line arguments as well, because they become visible in the process list.

The launcher therefore sets these variables only inside a subshell and starts the tool there. The token exists in that process and its children, but not in the shell from which I invoked it. This is not complete isolation, since child processes still inherit environment variables. It does, however, greatly narrow the scope compared with setting them for the entire shell.

At launch, I fetch the token directly from the credential server. The Keychain copy is refreshed every 10 minutes, so it can lag behind if the server rotates a token between updates. I have seen the server hold newer credentials than the local copy. It normally responds within 0.1 seconds, so the request adds little delay. I fall back to the cached copy only if there is no response within 5 seconds.

For Codex, the rotation worker keeps auth.json in the dedicated directory current, so the launcher only needs to set CODEX_HOME. The worker downloads credentials to a temporary file, checks that they are valid JSON, and replaces the existing file only if the contents differ. That avoids unnecessarily rewriting a file the running tool may be reading every 10 minutes. But it does not mean keeping an old copy indefinitely: the credential server handles token renewal, and even the same account can receive newly issued credentials. I have seen an old copy become invalid on the server.

Store keys and token copies in Keychain

I keep the credential server's access key and cached token only in macOS Keychain. Granting the security command access when storing them lets the launchd worker read them without a password prompt.

After setting things up, I check four places for exposed credentials: the invoking shell's environment, process arguments, shell history, and startup files such as .zshrc. I actually found a plaintext key in one of those files. A pasted shell configuration block used it as a fallback when an environment variable was missing. I changed it to read from Keychain and revoked the exposed key. Issuing a separate access key for each device also means that, if one device exposes its key, only that key needs to be revoked.

I learned three things while working with Keychain.

• An entered value can be truncated to 128 characters. Supplying a value through the prompt or standard input to security add-generic-password truncated it at 128 characters in my setup. The prompt does not display the input, and the confirmation is truncated in exactly the same way, so nothing looks wrong during entry. The OpenAI project key I was using began with sk-proj- and was 164 characters long, so it was truncated. For that key, I passed the value as an argument and accepted that it would briefly appear in the process list. After storing a value, I check its length, not just whether it exists. Exactly 128 characters is a warning sign of truncation in this workflow.
• Updating an existing entry can be slow. Overwriting an entry took 20 or 30 seconds. Just after restarting the rotation worker, it once took nearly 4 minutes. Creating a new entry at the same time took 0.03 seconds. Deleting the old entry and creating a new one brought the operation down to 0.5 seconds. There is a brief gap between deletion and creation, but the launcher asks the credential server first, so it did not affect launches in this setup.
• Resetting the login password can isolate the entire login keychain. Changing the password without supplying the old one prevents macOS from re-encrypting the login keychain with the new password. Resetting it from another administrator account is one example. macOS instead renames the old keychain to login_renamed_N and creates an empty one. The isolated keychain still requires the old password that was last synchronized with it; a FileVault recovery key cannot unlock it. In my case, more than 90 entries were locked. A year-old login_renamed_1 was already there too, showing that an earlier reset had silently done the same thing. I could not remember the old password, so I reissued the keys. To prevent this, change the password while logged in through System Settings → Touch ID & Password → Change Password. That flow asks for the old password, allowing the keychain to be re-encrypted too.

Run rotation in the background and keep it alive on failure

One shell script handles rotation. It fetches a token once at startup and stores it in Keychain, then checks the token's status with the credential server every 10 minutes. If the account is close to its limit or the token is unusable, it fetches new credentials and replaces the cached copy. Logs contain status information, not token values.

I keep the script running with launchd. It is registered as a user LaunchAgent, with RunAtLoad starting it at login and KeepAlive restarting it after exit. A plist does not expand ~ or $HOME, so its paths must be absolute.

The first version exited with an error if it could not fetch the initial token. That caused a serious problem: launchd restarted the process after its restart interval, set to 30 seconds through ThrottleInterval. If the credential server was temporarily unable to issue a token, or the access key was missing from Keychain, the script exited and restarted repeatedly, hitting the server every 30 seconds. It restarted 1,700 times over two days when it could not obtain a token. I changed it to stay alive on failure. It waits inside the loop until the key appears, or until the next polling interval if token retrieval fails. For a supervised script, "exit on failure" effectively meant "retry every 30 seconds."

Gaps in the logs that looked like failures turned out to be sleep. When the Mac sleeps, the rotation worker sleeps too. Comparing sleep timestamps from pmset -g log with the gaps makes this clear. The credential server chooses the account with the most available capacity for each request, so frequent account changes in Codex's 10-minute refresh logs can be normal.

What is automatic and what still needs a person

I automated only the preparation of new credentials. Switching an already-running session remains a manual step.

Claude Code reads the environment variables once at startup, and Codex reads auth.json when its session starts. Codex renews the current account's tokens itself during use. In my observations, however, replacing the file externally with another account's credentials did not switch the running session. Even after the worker replaces the cached copy with B, the active session keeps making requests with A. Once A reaches its limit, that session cannot continue. Ending it and starting again through the launcher loads the latest credentials. Its history remains in the dedicated directory, so I can continue with --resume. Closing the Codex desktop app's window does not stop its process; it must be fully quit and reopened to read the new credentials.

For headless use in scripts, check the launch options too. With --bare, Claude Code does not read CLAUDE_CODE_OAUTH_TOKEN. I omit --bare when using the shared subscription token. Usage-based API keys have official mechanisms such as apiKeyHelper that can fetch keys again while running. This post uses subscription tokens passed through an environment variable, so I restart the session.

Operating rules

The setup rests on three principles. Separate accounts with configuration directories, and share working preferences through links. Pass credentials only to the process being launched. Store them in Keychain and run the rotation worker through launchd.

Five practical rules came out of operating it.

1. Keep the shared account in a dedicated directory to avoid logging it out by accident.
2. Keep background workers alive on failure. A supervisor that immediately restarts them can turn failure into a restart loop.
3. Store credentials in Keychain and check their length after writing. To update an entry, delete it and create a new one.
4. Change the login password through the normal password-change flow instead of resetting it without the old password.
5. Automate preparing new credentials; restart sessions manually.

When working with Claude Code, there are moments when another agent's help would be useful: creating a blog cover image, checking newly written code for gaps from a different perspective, or deciding which of two outputs to adopt. You can open Codex separately, or connect the process so that Claude Code passes it the work and receives the results.

The starting point was a question: “Is there a skill for using Codex from Claude Code?” After investigating seven candidates, including the official plugin, I found that the first distinction to make was less about how many plugins exist and more about how Codex is invoked and how its results are verified.

This post has two parts. First, I compare the official plugin with direct CLI calls. Then I look at their application to image generation, adversarial review, and A/B evaluation. For image generation, I checked the saved execution logs and PNG. The other two use cases remain designs that have not yet been run.

What Did I Actually Verify?

The initial research took place on September 6, 2026, in a Windows 10 environment. The report records Claude Code 2.1.263 and Codex CLI 0.153.4. While preparing this post, I checked the findings again against the official documentation and plugin source as of September 7. The distinctions below are the basis for reading this post.

I did not install the official plugin. The ready: true in the source material records a check of the environment and authentication required to run it; it must not be read as meaning that every plugin feature worked correctly on this PC.

What Does the Official Plugin Connect?

OpenAI provides openai/codex-plugin-cc for Claude Code. The plugin I investigated was v1.0.6, and the code I inspected was at commit db52e28.

The invocation flow is as follows.

Claude Code의 /codex:* 명령
  → 플러그인의 Node 스크립트
  → 로컬 codex app-server
  → Codex 작업·리뷰
  → Claude Code로 결과 반환

Internally, the plugin starts a codex app-server process and exchanges requests through JSON-RPC. It is closer to a connection layer through which Claude Code invokes separate Codex tasks than a setting that adds a Codex model inside the Claude model. Execution code

The main commands are divided by role.

Reviews and delegated fixes have different permissions. In particular, rescue may lead to work that can modify files, so it should not be treated like a read-only review. Receiving review results and verifying the changes are also separate things.

Installation and Things to Check on Windows

The official README gives the following installation procedure inside Claude Code. This reproduces the official installation instructions; it is not a record of installation completed during this investigation.

/plugin marketplace add openai/codex-plugin-cc
/plugin install codex@openai-codex
/reload-plugins
/codex:setup

Node and the Codex CLI must be available, along with authentication for Codex. It is best to check the official installation guide at installation time for detailed requirements and commands.

On Windows, installation is not the only thing to check; termination, cancellation, and background-process behavior also matter. For example, issue #530 reports that the Stop hook waited for a long time in a particular Windows 11 environment even with the review gate disabled. Issue #525 describes a failure to force-terminate a process because of Git Bash path conversion. The latter report also describes conditions under which a graceful cancellation request is possible, so summarizing it as “cancellation does not work at all” would overstate the report.

These are reports from other users, not results I reproduced on this PC. The fact that related issues were open when I checked is a reason to investigate before adoption, but does not establish that the same problems occur in every Windows environment.

When I checked on September 7, 2026, the most recent commit on the default branch was from July 8. The interval between commits alone cannot establish that maintenance has stopped. When adopting it, look at the issues and change history for the features you need.

How Does a Direct CLI Call Differ?

Another approach is to run codex exec from a Claude Code tool or project skill without going through the plugin. You define the recurring command, input prompt, and location for the results yourself.

The choice comes down to whether you need the conveniences of the official plugin or prefer simpler inputs and outputs while accepting more things to manage yourself. Direct calls bypass this plugin's hooks and broker, but do not eliminate compatibility issues in the Codex CLI itself.

The community alternatives I investigated also need to be distinguished by their execution paths. For example, codex-in-claude wraps codex exec in its own MCP server. By contrast, claude-codex registers Codex's built-in mcp-server. Both descriptions mention MCP, but they are different implementations.

What the current official documentation marks as deprecated is the codex mcp-server command. This must not be interpreted as meaning that every community wrapper using MCP has been discontinued. The official documentation points to app-server and the official Claude Code plugin as alternatives. MCP server documentation

The Basic Shape of a Direct Call

The following configuration example reads changes in a repository from Git Bash and writes the result to a file. It is not an exact copy of the command used for the image-generation probe.

mkdir -p review-output
codex exec --sandbox read-only --json \
 --output-last-message review-output/result.md \
 "변경 사항을 읽고 실패 가능성이 있는 지점을 근거와 함께 정리해줘. 파일은 수정하지 마." \
 > review-output/events.jsonl

Here, --json records runtime events as JSONL, while --output-last-message saves the final response in a separate file. For automated processing, --output-schema can specify the structure of the final response. Check the exit code, failure events, and whether the result file exists together. Valid JSON alone does not guarantee accurate content. Non-interactive execution documentation

Use Case 1: Image Generation, Verified Through Logs and Files

The task I actually ran called the Codex CLI from Claude Code to create a blog cover image. The prompt requested Codex's built-in image-generation tool and asked it to save the result as sample-a.png. The subject measured was a cover concept for last30days.

The verified path used codex exec to invoke the built-in image_gen. This was not an experiment using a separately obtained Images API key and an API script. The built-in tool's availability still needs to be checked for the environment and account being used. Codex image-generation guide

The 77 seconds is not just image-model inference time. It is the full execution time, including task startup, context reading, image generation, file verification, and copying. It should not be compared with the tool's reported 38.4 seconds as though they were the same metric. Nor does one successful run establish average speed or repeatability.

The final usage event recorded 110,853 input tokens, of which 90,496 were cached, and 693 output tokens. These values describe that agent run; they are not a token cost for one image or a figure converted into money. Both the image-generation tool call and the agent's context processing need to be considered.

The practical lesson is that work remains after “an image was generated.” In the sample, marks resembling numbers remained around the calendar border despite a request for no text. Successful file creation and fulfillment of the visual requirements must be checked separately. Identify the result path for the current run, verify that the file really exists, check its dimensions and aspect ratio, and inspect whether its visual content is appropriate. Since several sessions may run simultaneously, it is also better to avoid simply picking whichever image file was created most recently.

Use Case 2: Design Adversarial Review to Produce Falsifiable Findings

Adversarial review is not a request to find as many defects as possible. It is a process of examining assumptions and failure conditions that the implementer may overlook from another perspective, and making the findings verifiable through code or tests.

A draft skill was written for this use case, but the actual verification loop was not run. The original draft also has two CLI-option locations that need to be fixed and rechecked on this PC. It is therefore not yet ready to install as a finished tool or to present as a method that “caught bugs.”

The core of the design is to separate the roles.

Claude Code: 요구사항과 변경 범위 정리
  → Codex: 읽기 전용으로 실패 조건·근거 검토
  → Claude Code: 지적을 코드·테스트로 재확인
  → 확인된 지적 수정
  → 테스트와 필요한 재검토

Give the reviewer a baseline for the changes, the target files, and the behavior that must be preserved. It is important that the reviewer read the actual changes and requirements, rather than relying only on the author's conclusion that the implementation is good.

The result should contain at least the following information.

• What could go wrong?
• What input or execution sequence triggers it?
• Which file, function, or code supports the finding?
• What check could reproduce or disprove it?
• What remains unverified?

For example, “There is a branch that changes the state to completed even when the save request fails, which can be checked with a test returning a failure response” is more useful for follow-up work than “Exception handling is insufficient.”

In operation, content judgments and execution status also need separate records. A completed review that found no issues must not be treated as the same approval as a timeout that produced no result. The design keeps failed runs marked as failures, caps the number of iterations, and accepts actual fixes only after checking their test results.

You can use the official plugin's /codex:adversarial-review, or create your own result format directly with codex exec --output-schema. That plugin feature and the custom draft skill examined here are separate implementations.

Use Case 3: Decide What You Are Comparing Before an A/B Evaluation

While organizing the report, I also found that the term “A/B testing” was being used for several different activities.

The first approach uses an LLM as a judge. For two blog covers, you can first define criteria such as “Does it convey the topic?”, “Is it readable on a small screen?”, and “Is there room for an overlaid title?” Hide the author or generation-model names, swap A and B, and present them again to check whether position affects the judgment. If the judgments conflict, leave the choice for human review instead of forcing a winner.

Models can be influenced by response order or length. This calls for pairwise comparisons with clear criteria, rather than just a single score, along with a process to check agreement with human judgment. OpenAI evaluation best practices

The second approach is an implementation experiment. Since changes can become mixed if two agents work in the same repository at once, the idea is to use separate workspaces created from the same baseline commit. Judging correctness should involve the same tests, build, and requirements checks, as well as the persuasiveness of the explanation. If the conditions differ, model differences become difficult to separate from workspace differences.

The third approach, a visitor experiment, requires separate instrumentation. A model preferring cover B is not evidence that readers clicked B more often. Improvements in click-through or conversion rates cannot be claimed before assigning actual traffic and measuring behavior. This investigation reviewed only the designs for all three types.

Separate Costs and Permissions by Task, Too

Using a plugin does not make Codex free. It uses the local Codex authentication: a ChatGPT login draws on that plan's Codex allowance, while an API-key login follows separate OpenAI Platform API billing. This image probe ran in the ChatGPT-login environment recorded in the report. Codex authentication, Pricing and usage guide

Claude usage is also incurred when Claude Code prepares the work and reads the results. The comparison therefore needs to cover the whole task: output quality, number of calls, context size, waiting time, and time spent on human verification.

Set permissions according to the role. Start code review in read-only mode, and grant the necessary scope of write access to tasks that need to create files. Read-only restricts file-writing permissions for tools run by Codex; it does not mean that the material is not sent to an external model. Which files and context are transmitted needs to be checked separately.

Applying This to This Blog

The operating approach I have outlined at this stage is clear. For image generation, start with the one verified path and check the result file, dimensions, and content every time. For code verification, narrow the scope in read-only mode and request findings whose evidence can be checked with tests. To choose between two outputs, define evaluation criteria first and retain a final human decision.

The official plugin is a candidate when you want to use the supplied review and task-management commands. Direct CLI calls are worth considering when, as with this blog, you want to begin with narrow tasks that have defined inputs and result files. With either path, separating responsibility for creation, review, and adoption, and retaining execution results is the starting point for using the two agents together.

This post was written from research material and an image-generation probe dated September 6, 2026, and checked against official documentation and plugin source on September 7. Image generation was measured once; this post does not claim completion of the official plugin installation, actual reviews, or A/B experiments. Local environment information in the original logs has been excluded from the public text, leaving only the relevant measurements.

When I discover a new development tool, I start with the official documentation. It is relatively easy to find out what it does and how to get started. But before deciding to adopt it, I have a different question: what do people who have tried it recently like, and where are they getting stuck?

Answering that question means moving between several places: reading user experiences on Reddit, finding developers' posts on X, watching demonstrations on YouTube, and checking related issues on GitHub. Checking publication dates and grouping similar discussions takes time, just as finding the material does.

last30days is an open-source skill for delegating this kind of research into recent trends to an AI agent. This post looks at what the tool does, how its research proceeds, where it is useful, and what its limitations are.

What Is last30days?

last30days researches a given topic with a focus on the past 30 days and summarizes material found across multiple platforms. It supports Reddit, X, YouTube, Hacker News, GitHub, and others, though the sources actually queried depend on the environment and configuration. The official GitHub repository describes the project and its support scope.

Here, a skill means a package of instructions for an AI agent and tools it can run. last30days includes both a SKILL.md describing the research procedure and Python code that performs the actual collection. The agent you use reads the instructions, runs the tools, and carries out the research. The project's explanation of its concepts

The focus is on recent community reactions. While official documentation is needed to verify features and conditions of use, the material gathered with last30days helps reveal what people experience when using those features.

For example, when considering a new library, you might read the release notes to understand the changes, then look for recurring frustrations or use cases in related discussions. Reading both can surface evaluation questions that a feature list alone does not reveal.

How Does It Conduct Research?

The workflow becomes easier to understand when you separate the AI agent's judgments from the Python engine's collection and organization work. On a host with web search and reasoning capabilities, the agent creates a search plan, passes it to the engine, and reads the collected results to write the final explanation. Depending on the environment, it may also use the engine's internal planning and ranking path. Skill execution instructions

1. 01Search plan
2. 02Collect material
3. 03Assess relevance, recency, and engagement
4. 04Deduplicate and organize evidence
5. 05Summarize results

1. Turn the Question into a Search Plan

First, clarify what is being investigated. Products or people may share a name, so the agent checks relevant accounts, repositories, and communities to narrow the target. It then divides the question into several subqueries and decides which sources each search should query.

For example, when asking how a particular library is regarded, user reviews and migration experiences are different search perspectives. Splitting the question is more effective at finding the necessary evidence than repeatedly searching the product name alone.

This step involves the model's interpretation of the user's question. That is why it helps to provide the type of product and what you want to know, rather than just a topic name.

2. Collect Material from Each Source

The Python engine queries multiple sources in parallel according to the plan. The material available differs by platform. It has to handle different forms of information, such as discussion posts and comments, video details and subtitles, and repository activity.

Installed CLIs, API keys, and authentication status affect the scope of the investigation. YouTube or X appearing on a support list and that source being successfully queried in the current run are separate facts. This is why the actual collection scope matters when reading the results.

3. Consider Relevance, Recency, and Engagement Together

Collected material is ranked using its relevance to the topic, how recent it is, and the level of response it has received. The information used for engagement also varies by platform: upvotes, comment counts, likes, and views are handled in a way suited to each source.

The initial ranking code in v3.23.0 that I checked locally assigns weights of 65% to relevance, 25% to recency, and 10% to engagement. These weights apply to the initial ranking within each search-result list. Results are subsequently merged and ranked again, so this should be distinguished from the scoring formula for the final report. Initial ranking code

The point is that engagement is one of several criteria. Even a highly viewed item is unlikely to help if it is unrelated to the question.

4. Merge Duplicates and Organize the Evidence

Different queries may find the same post. The engine merges duplicates by URL and combines their ranks across the search results. The technique used here is RRF, or Reciprocal Rank Fusion. Think of it as combining the ranking information for material that appears near the top of multiple lists. Result-merging code

Depending on the research type, it also clusters related material. Grouping posts about the same event or controversy, for example, makes it easier for the agent to identify the issues than reading scattered links one by one. Clustering code

However, similar posts across multiple platforms do not necessarily mean a fact has been independently confirmed. They may all be quoting the same announcement or original source. How widely material has spread and how independent the supporting evidence is must be judged separately.

5. The Agent Reads and Summarizes the Results

Finally, the agent reads the collected and organized evidence, then explains the main points and recurring patterns. How much was gathered from each source and which sources were inaccessible also affect how the results should be interpreted.

In addition to general research, it supports workflows such as comparisons and topic discovery. You can change the request to specify two tools to compare, for example, or ask it to find worthwhile research topics in a field of interest. Supported modes and options are described in the configuration documentation.

What Makes It Useful?

First, it can reduce the repetitive work of starting an investigation. Searching multiple sites, checking dates, and deduplicating links recur with every new topic. Once that process is delegated, the user can spend time selecting and reading the most relevant original sources.

Second, it lets you examine different kinds of material together. You can see whether a frustration from a user review is also being discussed in GitHub issues, or whether users have actually responded to a feature introduced in a video. The value of gathering multiple sources lies less in their number than in the opportunity to compare perspectives.

Third, it helps generate the next questions to investigate. Recurring installation problems, expectations for a feature, or conflicting assessments can give the research a clearer direction. When writing a blog post, this material can also help identify issues readers care about and check them again against official documentation.

It fits tasks that need recent context: researching a tool's reputation before adoption, checking reactions after a product update, or exploring discussion points before writing. It is especially useful as a starting point when you know the topic but do not know which original sources to read first.

Limitations to Keep in Mind

Popularity and Accuracy Are Different Criteria

Engagement shows which discussions attract attention. But many likes do not make a technical explanation accurate. Provocative claims and promotional content can also draw strong reactions.

Before citing a feature, performance figure, or support claim from a summary in your writing, check the official documentation or original source again. Community reactions are better read as material for understanding experiences and opinions.

An Inaccessible Source Is Not a Quiet Source

Expired authentication, rate limits, or network problems can prevent collection. If the result is zero items under those conditions, you cannot conclude that no relevant discussion exists.

The project instructs the agent to distinguish a successful query with no results from authentication failures, timeouts, and partial collection. doctor diagnoses configuration and source status, while doctor --postmortem helps identify problems using the last run's results. --preflight shows configuration origins and planned access and storage operations before the actual investigation. Diagnostics and execution instructions

Readers should check not only which claims a report makes, but also what material was available when those claims were formed.

The Material Varies by Topic and Language

There may not be enough useful material if the supported platforms have few relevant posts or the product name is ambiguous. Even when you ask in Korean and receive a Korean summary, the collected originals may lean toward English-language platforms.

If reactions from Korean-language communities matter, those communities also need to be investigated directly. A result written in Korean should not be interpreted as representative of Korean users' opinions merely because of its language.

The same caution applies to the 30-day window. Longstanding frustrations and long-term assessments are hard to capture in a short research window alone. Check the period setting alongside the actual dates of the material, and compare older sources separately if you want to understand longer-term changes.

Setup and Execution Have Costs

The cost of installing the skill and the cost of conducting research should be considered separately. Some access paths are free, but particular sources may require separate API keys or a logged-in session, and may incur usage-based charges. The agent also consumes the host's allowance when creating search plans and summaries. Source-specific configuration guide

If you choose a path that uses a browser session, you also need to understand which account it accesses. Starting with only the sources you need, checking the actual collection scope, and expanding from there is easier to manage.

Waiting time grows as more sources, comments, and subtitles are examined. For a question about a single fact, going straight to official documentation may be faster. The tool becomes more useful for questions that require gathering and reading many people's recent reactions.

Installation and Simple Usage Examples

For installation by host and runtime requirements, see the installation guide in the official README. Source-specific API keys and output options are covered in CONFIGURATION.md.

After installation, select the skill and provide both the research topic and its purpose. The following are examples of how to frame a question, not quotations from actual research results.

Use last30days to research recent migration experiences with Next.js App Router. Separate recurring problems from examples of solutions, and tell me which sources could not be checked.

Use last30days to compare recent user reactions to two development tools. Focus on team collaboration and extensions.

Naming the products precisely and narrowing the comparison criteria also clarifies which original sources you should verify once the results arrive.

An Actual Research Example: INTENT.md

A supplementary research report on INTENT.md saved on September 6, 2026, illustrates how last30days can be used. It examined how the practice of documenting intent and constraints connects to actual code changes, verification, and agent handoffs. Recent trends were scoped to August 7 through September 6, with older material classified as background.

Checking the original sources found in the results revealed different ways of applying the idea.

• X-GIS: A PR merged on September 5 added a new GitHub issue template for recording intent, constraints, rejected approaches, and completion checks, and linked it to the existing guidance. This captures intent when an issue is created instead of adding a separate document. PR and changed files
• callback: PR #81 replaced the collector based on requirements in INTENT.md and added verification material. It had not yet been merged when checked on September 6. The before-and-after collector performance figures need to be distinguished from measurements of the intent document's own effects. Original PR
• Pathmode: On August 30, it announced a fix for handoff records not reaching the next agent; on September 3, it announced a review feature tied to PR commits and intent-document versions. This review is advisory and does not block merging. Changelog

These three cases are evidence of attempts to connect intent documents to development workflows. However, finding adoption examples and proving productivity gains are different things. Effects described by a PR author or product vendor must not be read as results from an independent comparative experiment.

In this process, the last30days results provided a starting point for finding original sources to read and issues to compare. To turn them into evidence usable in an article, the actual changed files, merge status, and scope of the feature still need to be checked in those sources. Collection counts likewise describe the volume of search results, not the number of independent adoption cases.

Using It for Blog Research

For blog research, a suitable workflow is to find discussion points in the summary, then verify key claims against the linked originals and official documentation. Used that way, it reduces the effort of starting research while allowing you to examine the article's evidence yourself.

The feature descriptions are based on official documentation checked on September 6, 2026, and local v3.23.0 code. The case study was prepared by comparing an INTENT.md research report saved that day with its linked original sources. While supplementing this post, I did not rerun the research engine or measure productivity improvements. Supported sources and configuration methods may vary by version.

In one terminal window, Claude Code is refactoring the payment module. In another, Codex is writing tests for the feature deployed yesterday. The agent in the third tab has been quiet for ten minutes. You cannot tell whether it has finished, gotten stuck, or is waiting for your approval.

It is a scene many developers in 2026 have encountered. AI coding agents have improved rapidly, but the way we manage several of them still amounts to manually switching between terminal tabs. Orca, which has recently seen explosive growth on GitHub, targets exactly this problem. It calls itself a new category: an ADE (Agent Development Environment), rather than an IDE.

An ADE Instead of an IDE? Start with the Terminology

Orca was created by Stably AI (legal name: Lovecast Inc.). Founded by Jinjing Liang and Neil Parker in 2022, the San Francisco company went through Y Combinator's winter batch that same year. The team originally built QA automation products. Orca is effectively its next big bet.

The official site puts it this way: “IDEs were built for you. ADEs are built for you and your agents.” The opening page of the documentation makes an even more direct statement: “Not a model. Orca runs agents you already use.”

That sentence is the key to understanding Orca. Cursor, Windsurf, and GitHub Copilot are integrated products that bundle model access into a subscription. Orca, by contrast, does not sell models. It does not even have its own inline autocomplete. Instead, it runs and manages several agents you already subscribe to, such as Claude Code, Codex, and Cursor CLI, at the same time, serving only as their command center.

The Core Mechanism: Spread Agents Across git Worktrees

What happens when several agents are let loose in one repository at once? They edit the same files, overwrite each other's changes, and tangle the branches. That is the fundamental multi-agent problem.

Orca's solution is almost elegantly simple: give every task its own git worktree. A worktree is a native git feature that creates another working copy of the same repository on disk. Instead of repeatedly stashing changes and switching branches, you give each task a physically separate workspace from the start. As the official documentation puts it, “This is what makes parallel agents safe—they never step on each other's files.”

Each worktree also gets its own agent terminal and browser tab. Orca's full workflow can therefore be summarized as follows.

The most striking part is steps 4–6: fan-out and winner selection. Give the same prompt to 3–5 different agents simultaneously, let each solve the problem on its own branch, then compare the diffs side by side and merge only the best result. The official tutorial captures the experience well: “Three branches. Three diffs. Same prompt.”

A review video posted in July showed an interesting side effect. The reviewer said they gave five agents different tasks, but told only one about a bug. Three ended up finding it on their own. Running multiple perspectives in parallel lets one catch what another misses—an effect that may sound obvious, but is hard to appreciate until you actually try it.

Supported Agents and the Real Cost Structure

Orca's principle is clear: “If it runs in a terminal, it runs in Orca.” The official support list includes 25–30 or more agents, including Claude Code, Codex, Cursor CLI, Gemini, GitHub Copilot CLI, OpenCode, Grok, and Pi. You can also add custom CLI agents that are not listed.

Authentication is BYO—bring your own. Orca itself has no login and no per-seat fee. The app passes your existing subscription credentials to each agent CLI, which calls its provider's API directly from your computer. Orca takes no margin in between.

That produces the following pricing comparison.

How It Differs from Cursor and Windsurf: A Layer Above Them

You may see headlines calling Orca a “free Cursor killer.” That may attract traffic, but it does not accurately describe the product's structure. Orca is closer to a layer above Cursor than a replacement for it. In fact, Cursor CLI is one of Orca's supported agents.

Independent reviewers' conclusions support this picture. Their point is: “Orca wins when you want to use two or more agents. If you use only one agent and like its UI, stay there.”

In other words, if Cursor's inline autocomplete or chat panel is central to your work, Orca is not the answer. Even the official documentation explicitly says it is not a fit if all you need is simple autocomplete assistance. Orca targets “engineers running 10–100 coding agents at the same time.”

Competitors in the Same Space: Conductor, cmux, and Herdr

Interestingly, the “agent orchestrator” category itself has become crowded very quickly in 2026. In July alone, reviews comparing orchestrators appeared in such numbers that they seemed to form a genre of their own.

Emerging tools such as Herdr have joined the field too. A “Herdr vs Orca” comparison video posted in mid-July drew nearly 5,000 views. Its central question captures the category well: “How do you give developers visibility and control over a fleet of agents without turning them into full-time managers?”

Three features are often cited as Orca's differentiators. First, a mobile companion: receive a notification when an agent finishes and send follow-up instructions from your phone. A Japanese-language podcast singled out the fact that “the agents keep running even after you close your computer” as the most impressive part. Second, Design Mode: click a UI element in an actual Chromium window, and its HTML, CSS, and a cropped screenshot go straight into the agent's prompt. Third, remote worktrees over SSH let you run work on a remote machine.

Install It and Run Three Agents in Five Minutes

Installation is straightforward. However, there is one trap for Mac users.

# macOS - 반드시 tap 경로를 명시할 것
brew install --cask stablyai/orca/orca

# Arch Linux (AUR)
yay -S stably-orca-bin

After installation, the first guide in the official documentation is the “first three-agent session” tutorial. It says going from an empty app to three agents running in parallel takes less than five minutes. The flow is as follows.

1. Create a worktree. A terminal opens in the new worktree. Choose Claude Code, Codex, Cursor CLI, or another agent in the selector, and Orca launches the CLI in the correct working directory and passes it your subscription credentials.
2. Repeat the process twice to create three worktrees in total.
3. Paste the same prompt into all three agents.
4. Drag the worktree tabs to the edges of the screen to split the view and watch all three agents at once.
5. When they finish, open each worktree's diff view and compare. You can also add inline comments with Annotate AI Diff and send them back to the agent whose result is closest to what you want.
6. Commit and push directly from Orca, then clean up the other two worktrees and their branches with one click.

What the Community Says, and What to Watch Out For

The speed of growth is itself the project's biggest news. A review video from early July said it had “passed 11,100 stars” at recording time. By late July, the repository's live count was 32,135 stars—nearly three times as many in a month. Releases arrive almost daily, and open issues have passed 2,500. Reviewers praise the team for triaging feature requests posted on Discord within a day.

First impressions are generally positive too. Review quotes such as “I didn't expect it to be this good” and “Everything gets so much easier” stand out, while video comments include reactions like “That explanation was really concise. I'm going to try Orca.”

For balance, however, most signals currently available come from YouTube reviewers, personal blogs, and small Reddit threads. There is still little accumulated critical scrutiny of the kind found in major Hacker News discussions or large-scale usage reports. As always with a young tool, early reviewers' enthusiasm needs to be taken with a grain of salt.

Three limitations have been raised repeatedly so far.

• It is overkill for single-agent users. If you use only one agent, Orca offers little benefit.
• Costs scale with the number of parallel agents. That applies to token consumption and disk usage per worktree alike.
• Without agent subscriptions, it is an empty shell. Orca itself cannot generate anything.

One amusing footnote: a Reddit commenter noted the name's similarity to MacStadium's macOS virtualization product Orka and quipped, “I don't think that name is going to last.” Naming collisions are indeed a practical problem for search traffic in this category.

Conclusion: Is It the Right Tool for You?

Orca in one sentence: a free, open-source command center that sells no model, but lets you run the agents you already have simultaneously in isolated worktrees.

If the competitive focus in AI coding tools is shifting from “Which model is smarter?” to “How do we manage multiple agents?”, Orca is one of the clearest examples. If it interests you, I recommend spending five minutes on the official three-agent tutorial. That is enough to get a feel for it.

On June 12, Google quietly released a specification called Open Knowledge Format (OKF), introducing it as a “vendor-neutral standard for delivering organizational knowledge to AI agents.” Six weeks later, on July 25, v0.2 arrived, directly addressing the question: “Can an agent trust this knowledge?”

A new standard usually attracts plenty of introductions, but marketing language and the actual specification often differ subtly. OKF was no exception. So this post takes a slightly different approach: cross-checking every claim against the original specification (SPEC.md) and official announcements, and labeling what is verified and what is not. An article introducing a standard about the provenance and trustworthiness of knowledge should probably be written that way too.

What Is OKF?

OKF is an open specification that represents organizational knowledge—metric definitions, table schemas, APIs, and runbooks—as a directory of Markdown files with YAML frontmatter. Its structural rules can be summarized in three lines.

• One file = one concept
• The file path, minus .md, is the concept's ID
• Relationships between concepts are ordinary Markdown links—as links accumulate, the whole directory becomes a relationship graph

The most striking feature is the specification's minimalism. In numbers:

In other words, the file below is a fully conformant OKF concept on its own.

# runbooks/deploy-rollback.md
---
type: Runbook
---
배포 롤백 절차는 ...

Google Knows It Is “Nothing New”

“What is new about adding frontmatter to Markdown? How is this different from Obsidian?” These were among the most common community reactions after OKF's announcement. Interestingly, Google itself raises this point in the launch blog post.

“Similar knowledge-as-Wiki pattern keeps reappearing under different names: Obsidian vaults wired to coding agents, the AGENTS.md / CLAUDE.md family of convention files ... each instance is bespoke. OKF formalizes the small set of conventions needed to make these patterns interoperable.”
— Google Cloud launch blog post

The launch post links directly to Karpathy's LLM Wiki idea and defines OKF as a formalization of the “LLM-wiki” pattern. Its value proposition was therefore standardized interoperability, rather than technical novelty, from the outset: put common conventions around the bespoke “Markdown knowledge folders” built for each agent and company, making them portable.

v0.2: “Can This Knowledge Be Trusted?”

If v0.1 defined how to represent knowledge, v0.2 is about trust. The Google blog organizes what an agent should assess when reading a concept file into five questions: What was it derived from (provenance)? How much can it be trusted (trust)? Is it still valid (freshness)? Is it the latest version (lifecycle)? Was it computed as promised (attestation)?

The Actual Field Structure

Reconstructing v0.2 frontmatter from the specification's examples gives the following.

---
type: Metric
title: Quarterly Revenue
generated:            # 누가·언제 만들었나
  by: reference_agent/gemini-2.5-pro
  at: 2026-06-20T22:53:05Z
verified:             # 누가·언제 검증했나 (작성자와 별개)
  - by: human:ahormati
    at: 2026-06-25T09:00:00Z
sources:              # 출처 — 엔트리당 필수는 resource 하나
  - id: rev-policy
    resource: https://wiki.acme/finance/revenue-recognition
status: stable        # draft | stable | deprecated (생략 시 stable)
stale_after: 2026-12-31  # 이 날짜가 지나면 stale
---

Two details in the design stand out:

• The deliberate separation of generated and verified—in the official blog's words, because “who wrote it and who checked it do not have to be the same actor.” The field structure directly reflects a pipeline in which AI creates the content and a human verifies it.
• Actor notation (§7)—agents and tools use producer/version, such as reference_agent/gemini-2.5-pro, while humans use a value such as human:ahormati with the human: prefix. That prefix is the key to deriving the trust tiers below.

Three Levels of Trust: Machine-Readable Trust Tiers

A consumer, usually another agent, derives one of three trust tiers for a concept from the verified field alone.

Backward Compatibility: Exactly Two Renames

v0.2 is an additive minor bump with exactly two intentional renames: v0.1's timestamp → generated.at, and the body’s # Citations list → sources frontmatter. In the specification's words, “A v0.1 bundle drops in unchanged.” Existing bundles work without modification.

How Does It Relate to AGENTS.md and CLAUDE.md?

If you use Claude Code or another coding agent, you are probably already supplying context through convention files such as CLAUDE.md and AGENTS.md. Does OKF replace those? A community FAQ offers a clear distinction.

"AGENTS.md tells an agent how to behave. OKF tells an agent what exists in the world. They're friends, not competitors."

“Throw Away Your Vector DB”? The Specification Does Not Say That

A community narrative has grown around OKF: “Abandon vector DBs and RAG, and return to a Markdown link graph.” The claim is that following explicit links instead of approximate similarity search removes both embedding costs and hallucination risk.

The Ecosystem and Its Reception

For an ecosystem only six weeks past launch, things are moving quickly. The specification repository has gathered about 8K stars, and both the launch and v0.2 announcement have HN threads with active debate. One notable third-party tool is the Ruby ecosystem's serradura/okf-gem. It packs authoring through an agent skill, specification validation, linting with CI exit codes, full-text search, knowledge-graph visualization, and even a Claude Code plugin into one gem, running 100% locally.

Wrapping Up: Is It Worth Trying Now?

Here is my assessment.

• The adoption cost is effectively zero. If you already write documentation in Markdown, you can start by adding a single type line to the frontmatter, with everything versioned in git. Even if the specification is abandoned, what remains is a well-organized Markdown folder. There is nothing to lose.
• v0.2's real contribution is standardizing trust metadata. Making the pipeline “AI generates → human verifies → validity period specified” machine-readable through three fields (generated/verified/stale_after) is a practical design for an era in which agents consume one another's outputs.
• But it is still a draft. Fields may change further, just as renames occurred between v0.1 and v0.2. At this stage, applying it experimentally to one knowledge folder read by an agent seems more appropriate than enforcing it as an organizational standard.

Personally, since I already use Claude Code's memory directory and CLAUDE.md, I plan to try the division “CLAUDE.md for behavior, OKF bundles for knowledge” in a side project. I will share a follow-up once results accumulate.

Enter a Jira issue key. The agent calls the Jira API to automatically collect the issue body, comments, attachments, linked issues, and change history. It analyzes the collected data and source code to write a development specification, then cross-checks it itself. From that specification, it creates a file-by-file development plan and verifies the plan too. It creates an isolated environment with a Git worktree, writes the code, and takes it through five stages of verification: functionality, types, security, performance, and code quality. Finally, it generates a completion report covering the entire process.

All the human did was enter the issue key.

지라 이슈 키 입력
  │
  ├─ 1. 이슈 컨텍스트 수집 ─── 지라 API → context.json + report.md
  │
  ├─ 2. 스펙 생성 ──────────── 컨텍스트 + 코드 분석 → spec.md
  ├─ 3. 스펙 리뷰 ──────────── 팩트 체크 + 범위 검증 → APPROVED / REGENERATE
  │
  ├─ 4. BDD 시나리오 ────────── Given-When-Then 도출 (조건부)
  ├─ 5. 개발 계획 ──────────── 파일 단위 태스크 + 코드 스니펫 → dev-plan.md
  ├─ 6. 계획 리뷰 ──────────── 스펙 커버리지 + 경로 검증 → APPROVED / REGENERATE
  │
  ├─ 7. 격리 환경 구성 ─────── Git worktree + 의존성 설치
  ├─ 8. 자동 개발 ──────────── TDD 사이클, 태스크 단위 커밋
  │
  ├─ 9. 5단계 검증 ─────────── 기능 → 타입 → 보안 → 성능 → 품질
  ├─ 10. E2E 테스트 ─────────── 브라우저 자동화 (조건부)
  │
  └─ 11. 완료 보고서 ────────── 전체 산출물 종합 + HTML 시각화

This post shares the four design principles behind the pipeline and how to implement it using the Claude Code skill system.

Harness Engineering: What Did I Actually Build?

My earlier post, Harness Engineering: The Developer's New Role in the Age of AI Agents, introduced the concept. The model is the CPU; the harness is the OS. Harness engineering means designing everything outside the agent: CI, linters, tests, observability, and AGENTS.md.

The concept makes sense, but a question remains: **“What should I actually build?”** This post answers that question. It documents a practical implementation of harness-engineering principles in Jira-driven development automation.

The Problem I Wanted to Solve

Most AI coding workflows currently look like this.

"이 지라 이슈 보고 코드 만들어줘" → 코드 생성 → 끝

There are two problems.

First, the context bottleneck. Open a Jira issue. Requirements are in the body, additional explanations from the product planner are in the comments, screen designs are in attachments, related bug reports are in linked issues, and revised acceptance criteria are in the change history. Even developers do not read all of this carefully. For AI, they copy and paste only the issue body. However sophisticated the prompt, incomplete input produces incomplete output.

Second, the limits of one-shot generation. Generate code without a specification, and requirements get missed. Generate tests without one, and coverage falls short. Human developers go through analysis → design → implementation → verification, yet we ask AI to “do everything in one go.”

Apply the core principles of harness engineering—structured context, architectural constraints, and feedback loops—to this problem, and you end up designing a stage-by-stage pipeline rather than a single prompt. Define each stage's inputs and outputs, put verification gates between stages, and create retry loops for failures. The harness defines the agent's sequence of work, quality standards, and input/output framework.

Four Design Principles

Here are the four principles I repeatedly relied on when applying general harness-engineering principles to this pipeline.

Principle 1: Automate Context Collection

Let the agent gather the context it needs itself.

Having humans organize and hand over context creates two problems. First, information loss: people pass along only what they consider important, leaving things out. Second, a bottleneck: however fast the agent is, it is bound by the speed of the human preparing its context.

The solution is to let the agent collect it directly. It automatically gathers the full issue data through the Jira API, reads the source code to identify the scope of impact, and analyzes DB schemas to understand the data structures.

The key principle is **“Collect broadly, refine in the next stage.”** Filtering during collection can omit important information because of a mistaken judgment. It is safer to fetch everything first and extract the relevant information during specification generation.

This principle extends beyond the explicit collection stage. An agent reading existing code to learn its patterns while planning development, or finding and referencing related files during automated development, is also automating context collection.

Principle 2: Refine in Stages

Build a pipeline in which each stage's output becomes the next stage's input.

Instead of generating code in one shot, progressively refine raw data → specification → plan → code. Each stage produces a clearly defined format, such as Markdown or JSON. A fixed format ensures the quality of the next stage's input.

This structure has another benefit: every intermediate artifact remains as a file. Specifications, plans, development logs, and verification results each have their own files, making it possible to trace where a decision was made afterward. When an agent generates incorrect code, you can trace back whether the specification, plan, or implementation was wrong.

Retaining intermediate artifacts also creates review points where a human can intervene. The entire process can run automatically, but a semi-automated mode is also possible, with a human checking the specification before proceeding.

Principle 3: Self-Verification Loops

Always include a stage that independently cross-checks the generated result.

AI gets things wrong with confidence. If generation and verification happen in the same context, the same bias lets the result pass. Even if it asks itself, “Is this specification correct?”, it answers yes because it wrote it.

The solution is to separate generation from verification.

스펙 생성 (Step 2) ──→ 스펙 리뷰 (Step 3)
                        │
                        ├─ APPROVED → 다음 단계로
                        ├─ REVISE → 리뷰어가 직접 수정
                        └─ REGENERATE → Step 2 재실행 (최대 2회)
 
개발 계획 (Step 5) ──→ 계획 리뷰 (Step 6)
                        └─ 동일한 판정 루프
 
자동 개발 (Step 8) ──→ 5단계 검증 (Step 9)
                        │
                        ├─ PASS → 다음 단계로
                        └─ FAIL → 수정 후 재검증 (최대 5회)

Verification evaluates the result from a different perspective than generation. Specification review focuses on fact checks such as “Does this file path actually exist?” and “Does this table actually exist?” It checks verifiable facts, rather than abstract judgments.

Capping retries matters. Without a cap, the system can loop forever or keep consuming tokens while repeating the same mistake. At the cap, escalate to a human. Explicitly saying “This stage cannot be resolved automatically” is better than proceeding on guesses.

Principle 4: Isolate the Environment

Isolate the automation environment from the original.

In a system where AI agents edit code directly, the greatest risk is contaminating the original. If incorrect code is applied directly to the original repository, it becomes difficult to undo.

Use Git worktrees to create an independent environment for each issue. Keep the original repository untouched and work in a separate branch and directory for every issue. If it fails, delete the worktree. If it succeeds, merge through a PR.

repos/                          ← 원본 (절대 수정하지 않음)
├── frontend/
├── backend/
└── ...
 
worktrees/                      ← 이슈별 독립 환경
├── PROJ-1234/
│   ├── reports/                ← 산출물 (스펙, 계획, 검증 결과)
│   ├── frontend/               ← git worktree (독립 브랜치)
│   └── backend/                ← git worktree (독립 브랜치)
└── PROJ-5678/
    └── ...

Even several issues can be worked on simultaneously without conflicts because each worktree has its own branch, dependencies, and directory.

Mapping Principles to the Pipeline

Here is where the four principles apply in the 11-stage pipeline. ● marks a stage's core principle; ○ marks a supporting principle.

Pipeline Design in Detail

The following describes each stage's purpose, specific behavior, and input/output formats.

Issue context collection

This is the pipeline's starting point. It calls the Jira REST API v2 to automatically collect all data related to the issue.

Collection scope:

The output is generated in two formats.

{
  "issue": {
    "key": "PROJ-1234",
    "summary": "주문 상세 페이지에 배송 추적 기능 추가",
    "description": "...",
    "type": "feature"
  },
  "comments": [
    { "author": "PM Kim", "body": "배송사 API 연동 필요", "created": "2026-03-28" }
  ],
  "attachments": [
    { "filename": "shipping-ui-design.html", "content": "..." }
  ],
  "linked_issues": [
    { "key": "PROJ-1100", "summary": "배송사 API 인증 구현", "relation": "is blocked by" }
  ],
  "changelog": [
    { "field": "description", "from": "...", "to": "...", "date": "2026-03-30" }
  ]
}

## PROJ-1234: 주문 상세 페이지에 배송 추적 기능 추가
 
### 이슈 요약
- 유형: feature
- 보고자: PM Kim
- 생성일: 2026-03-25
 
### 댓글 (3건)
1. PM Kim (03-28): 배송사 API 연동 필요
...
 
### 연결 이슈 (1건)
- PROJ-1100: 배송사 API 인증 구현 (is blocked by)

The design principle is **“Collect broadly, refine in the next stage.”** This stage does not judge which information is important. That judgment belongs to specification generation.

Specification Generation + Specification Review

This is the most important stage of the pipeline. It turns the collected context into a specification ready for development.

Inputs to specification generation:

• context.json (output of the previous stage)
• Source-code analysis (the agent reads the codebase directly to identify the impact scope)
• DB schema (inspect the database structure if needed)

Specification-generation output (spec.md):

Test strategy by issue type:

This classification determines whether BDD scenario generation and E2E tests run conditionally later.

Specification review cross-checks the generated specification. It uses a verifiable checklist rather than abstract judgment.

There are three decisions: APPROVED proceeds to the next stage, REVISE lets the reviewer edit directly, and REGENERATE regenerates the specification from scratch. REGENERATE is allowed at most 2 times; if it still does not pass, the issue is escalated to a human.

BDD + Development Plan + Plan Review

Once finalized, the specification is converted into an executable plan.

BDD scenarios are generated only for feature and enhancement issues. The specification's acceptance criteria are converted into Given-When-Then form.

Feature: 주문 상세 페이지 배송 추적
 
  Scenario: 배송 중인 주문의 추적 정보 표시
    Given 주문 번호 "ORD-001"이 배송 중 상태이다
    When 사용자가 주문 상세 페이지를 연다
    Then 배송 추적 정보가 표시된다
    And 현재 배송 위치가 지도에 표시된다
 
  Scenario: 배송 전 주문은 추적 정보 없음
    Given 주문 번호 "ORD-002"가 결제 완료 상태이다
    When 사용자가 주문 상세 페이지를 연다
    Then "배송 준비 중" 메시지가 표시된다
    And 배송 추적 섹션은 비활성화된다

The **development plan (dev-plan.md)** breaks the specification into file-level tasks. Each task includes the files to change, the changes required, and runnable code snippets. The standard is clear: “Detailed enough that an outside developer could implement it from this plan alone.”

### Task 3: 배송 추적 API 엔드포인트 추가
 
**파일:**
- Create: `app/routers/shipping.py`
- Modify: `app/main.py` (라우터 등록)
- Test: `tests/routers/test_shipping.py`
 
**단계:**
1. Pydantic 스키마 정의
   - ShippingTrackingResponse: tracking_id, status, location, updated_at
2. 라우터 함수 구현
   - GET /api/orders/{order_id}/shipping
   - 배송사 API 호출 → 응답 변환 → 반환
3. main.py에 라우터 등록
4. 테스트 작성 및 실행

Plan review checks two things: whether every requirement in the specification has been broken into tasks (coverage), and whether the file paths in those tasks actually exist (fact-checking). It uses the same APPROVED / REVISE / REGENERATE decisions as specification review.

Isolated Environment + Automated Development

Once the plan is finalized, prepare the environment in which the code will be written.

Isolated environment setup:

1. Create Git worktrees only for projects within the specification's impact scope
2. Create a branch based on the issue key (for example, developer/PROJ-1234)
3. Install dependencies (npm install, pip install, etc.)
4. Provision environment variables

For an issue that changes the frontend, create worktrees for both the frontend and backend, because API tests need the backend.

Automated development executes the plan's tasks in sequence.

Create a commit for each task and include the issue key in the commit message.

feat(shipping): 배송 추적 API 엔드포인트 추가
 
JIRA: PROJ-1234

Five-Stage Verification + E2E Tests

Once the code is complete, run five consecutive verification stages. Run all of them in the order 1 → 2 → 3 → 4 → 5, without stopping midway.

If even one stage fails, fix the code and rerun all five stages from the beginning. There is no partial revalidation: a security fix can break functionality, and a performance improvement can break types.

Retries are capped at 5. After 5 failures, mark the work “unable to complete development automatically” and escalate to a human. Record where it failed and what was attempted in the report.

E2E tests use browser automation. Start the server, open it in a browser, check for console and network errors, and capture screenshots of the main screens. This stage applies only to feature/enhancement issues with a UI.

Report generation

This is the pipeline's final stage. It consolidates every artifact from the preceding 10 stages.

The completion report includes:

• Issue summary and classification
• Key specification details
• Changed-file list and git commit log
• Five-stage verification results (passes and failures)
• E2E test screenshots, where applicable
• Retry and escalation history

It also generates a visual HTML report. This is a single HTML file with images and screenshots embedded inline, so you can open it directly in a browser to review the full work history.

Error-Handling Strategy

Error handling is central to a system that runs 11 stages automatically. A unified strategy applies throughout the pipeline.

The core principle is **“Do not guess.”** If a file path does not exist, stop instead of guessing a similar path. If a test fails unexpectedly, stop instead of guessing the cause. Code an agent creates by proceeding on guesses causes bigger problems later.

Implementation Guide: The Claude Code Skill System

Here is how to implement this pipeline using Claude Code's custom slash-command (skill) system.

Skill Architecture Overview

Claude Code skills are Markdown files in the .claude/skills/ directory. They can be invoked with /슬래시 커맨드 and serve as instructions for the agent to read and follow.

.claude/
└── skills/
    ├── orchestrator/            # 마스터 스킬 (유일한 진입점)
    │   └── SKILL.md
    ├── jira-collector/          # 이슈 컨텍스트 수집
    │   ├── SKILL.md
    │   └── scripts/
    │       ├── collect.py       # 지라 API 수집 스크립트
    │       └── api_client.py    # HTTP 클라이언트
    ├── spec-generator/          # 스펙 생성
    │   └── SKILL.md
    ├── spec-reviewer/           # 스펙 리뷰
    │   └── SKILL.md
    ├── bdd-explorer/            # BDD 시나리오 (조건부)
    │   └── SKILL.md
    ├── dev-planner/             # 개발 계획
    │   └── SKILL.md
    ├── plan-reviewer/           # 계획 리뷰
    │   └── SKILL.md
    ├── worktree-creator/        # 격리 환경 구성
    │   ├── SKILL.md
    │   └── scripts/
    │       └── create-worktree.sh
    ├── developer/               # 자동 개발
    │   ├── SKILL.md
    │   └── references/          # 프로젝트별 코딩 가이드
    │       ├── backend.md
    │       └── frontend.md
    ├── verifier/                # 5단계 검증
    │   ├── SKILL.md
    │   └── references/
    │       ├── security-checklist.md
    │       └── quality-checklist.md
    ├── e2e-tester/              # E2E 테스트 (조건부)
    │   └── SKILL.md
    └── reporter/                # 보고서 생성
        └── SKILL.md

The core structure is that each skill is independent. Skills pass data through the file system: spec-generator reads the context.json created by jira-collector, and dev-planner reads the spec.md created by spec-generator.

The Structure of a SKILL.md File

SKILL.md is an instruction document, rather than code. It is Markdown that the agent reads and follows, defining procedures, output formats, and error conditions in natural language.

---
name: spec-generator
description: 수집된 컨텍스트를 기반으로 개발 명세서를 생성한다
---
 
## 입력
- `{REPORTS_DIR}/research/jira/context.json` — 지라 수집 데이터
- 소스 코드 — 에이전트가 직접 코드베이스를 읽어 분석
 
## 실행 절차
1. context.json을 읽고 이슈 유형을 분류한다 (feature/bug/enhancement/refactor)
2. 이슈 유형에 따라 TDD/BDD/E2E 플래그를 결정한다
3. 영향 범위에 해당하는 소스 코드를 읽어 현재 구조를 파악한다
4. 아래 템플릿에 맞춰 spec.md를 작성한다
 
## 출력
- `{REPORTS_DIR}/spec/spec.md`
 
## 출력 포맷
(마크다운 템플릿 정의)
 
## 에러 처리
- 소스 코드 경로를 찾을 수 없으면 즉시 중단하고 보고한다
- context.json이 비어있으면 이전 단계 실패로 판단하고 중단한다

The same structure applies to all 11 skills: four sections for inputs, procedure, outputs, and errors.

The Orchestrator Pattern

The orchestrator is a master skill that invokes the 11 skills in sequence. When the user enters /orchestrator PROJ-1234, it runs the remaining 10 skills in order.

Step 1:  /jira-collector      → context.json 생성
Step 2:  /spec-generator       → spec.md 생성
Step 3:  /spec-reviewer        → APPROVED?
         └─ NO → Step 2 재실행 (max 2)
Step 4:  if spec.BDD == true
         └─ /bdd-explorer      → bdd-scenarios.md
Step 5:  /dev-planner          → dev-plan.md
Step 6:  /plan-reviewer        → APPROVED?
         └─ NO → Step 5 재실행 (max 2)
Step 7:  /worktree-creator     → 격리 환경 준비
Step 8:  /developer            → 코드 작성 + 커밋
Step 9:  /verifier             → 5단계 검증
         └─ FAIL → 수정 후 재검증 (max 5)
Step 10: if spec.E2E == true
         └─ /e2e-tester        → 테스트 보고서
Step 11: /reporter             → 완료 보고서

Conditional execution (Steps 4 and 10) and retry loops (Steps 3, 6, and 9) are the heart of the orchestrator. It checks each stage's output and decides the next stage according to the conditions. If a blocker occurs, it stops immediately and reports to a human.

The Jira API Integration Skill

Jira data collection is implemented as a Python script and executed through Bash from the skill. It uses only the Python standard library—urllib and json—with no external dependencies, because it needs to run in the deployment environment without installing packages.

import urllib.request
import json
import base64
 
class JiraClient:
    def __init__(self, server_url, username, password):
        self.server_url = server_url
        credentials = base64.b64encode(
            f"{username}:{password}".encode()
        ).decode()
        self.headers = {
            "Authorization": f"Basic {credentials}",
            "Content-Type": "application/json"
        }
 
    def get_issue(self, key, expand="renderedFields,changelog"):
        url = f"{self.server_url}/rest/api/2/issue/{key}?expand={expand}"
        req = urllib.request.Request(url, headers=self.headers)
        with urllib.request.urlopen(req) as resp:
            return json.loads(resp.read())
 
    def search_issues(self, jql, fields=None, max_results=50):
        url = f"{self.server_url}/rest/api/2/search"
        data = json.dumps({"jql": jql, "maxResults": max_results})
        req = urllib.request.Request(
            url, data=data.encode(), headers=self.headers
        )
        with urllib.request.urlopen(req) as resp:
            return json.loads(resp.read())

def collect(jira_key, config, output_dir):
    client = JiraClient(**config["jira"])
 
    # 1. 메인 이슈 수집
    issue = client.get_issue(jira_key)
 
    # 2. 댓글 추출
    comments = extract_comments(issue)
 
    # 3. 첨부파일 다운로드 + 텍스트 추출
    attachments = download_attachments(issue, output_dir)
 
    # 4. 연결 이슈 1-depth 수집
    linked = collect_linked_issues(client, issue)
 
    # 5. 변경 이력 추출
    changelog = extract_changelog(issue)
 
    # 6. 외부 URL 크롤링
    urls = extract_and_fetch_urls(issue, comments)
 
    # 7. context.json 저장
    context = {
        "issue": normalize_issue(issue),
        "comments": comments,
        "attachments": attachments,
        "linked_issues": linked,
        "changelog": changelog,
        "external_urls": urls
    }
    save_json(context, f"{output_dir}/context.json")
 
    # 8. report.md 생성
    generate_report(context, f"{output_dir}/report.md")

The skill's SKILL.md invokes the script as follows:

## 실행 절차
1. config.json에서 지라 서버 URL과 인증 정보를 읽는다
2. 다음 명령으로 수집 스크립트를 실행한다:
   `python scripts/collect.py --key {JIRA_KEY} --output {REPORTS_DIR}/research/jira`
3. 실행 결과를 확인한다:
   - context.json이 생성되었는지 확인
   - 이슈 본문이 비어있지 않은지 확인
4. 에러 시 즉시 중단하고 에러 메시지를 보고한다

The Specification-Generation Skill

This skill synthesizes context.json and code-analysis results to create spec.md. The key is to enforce the output format with a template.

Define a Markdown template for spec.md in SKILL.md, and the agent writes to that structure. Include section order, required items, and flag formats in the template.

## 이슈 분류
- 유형: {feature | bug | enhancement | refactor}
- TDD: {O | X}
- BDD: {O | X}
- E2E: {O | X}
 
## 요구사항
(context.json에서 추출한 기능 요구사항을 번호 목록으로)
 
## 수용 기준
(완료 조건을 체크리스트 형태로)
 
## 영향 범위
| 프로젝트 | 파일 | 변경 내용 |
|----------|------|-----------|
(에이전트가 코드 분석 후 채움)
 
## 기술 결정사항
(설계상 선택과 근거)

Issue-classification logic is also defined in natural language in SKILL.md:

## 이슈 분류 기준
- **feature**: 새로운 기능 추가 (기존에 없던 화면, API, 로직)
- **bug**: 기존 기능의 오작동 수정
- **enhancement**: 기존 기능의 개선 (UI 변경, 성능 개선, UX 개선)
- **refactor**: 동작 변경 없이 코드 구조 개선
 
분류에 따른 플래그:
- feature → TDD: O, BDD: O, E2E: O
- bug → TDD: X, BDD: X, E2E: UI 관련이면 O
- enhancement → TDD: O, BDD: 사용자 시나리오 변경이 있으면 O, E2E: O
- refactor → TDD: O, BDD: X, E2E: X

The Verification Skill

The verification skill defines the checklist for each of the five stages in SKILL.md, and the agent executes them in sequence.

### Stage 3: 보안 검증 (OWASP Top 10)
 
다음 체크리스트를 변경된 코드에 적용한다:
 
- [ ] SQL 쿼리에 파라미터 바인딩 사용 여부
- [ ] 사용자 입력의 XSS 이스케이핑 여부
- [ ] 인증/인가 게이트 존재 여부 (API 엔드포인트)
- [ ] CSRF 토큰 검증 여부 (상태 변경 요청)
- [ ] 민감 정보(비밀번호, 토큰) 로깅 여부
- [ ] 파일 업로드 검증 여부 (타입, 크기)
 
위반 항목이 있으면:
1. 위반 내용과 파일:라인 번호를 기록한다
2. 코드를 수정한다
3. FAIL로 판정한다 (전체 5단계 재실행 트리거)

The orchestrator controls the retry loop. The verification skill returns only PASS or FAIL; on FAIL, the orchestrator runs the fix → reverify loop.

The Remaining Skills and Customization Points

The three skills covered above—collection, specification generation, and verification—represent the pipeline's main patterns. The remaining skills follow the same structure: define inputs, procedure, outputs, and errors in SKILL.md, read the previous stage's output files, and execute the next stage.

Points readers can adapt to their own projects:

Managing Cost and Tokens

One run of the 11-stage pipeline makes numerous LLM calls. Without attention to cost, a single issue can consume tens of dollars.

Cost-optimization strategies:

Actual costs vary greatly with project size, issue complexity, and model choice. I recommend starting with simple issues, measuring token consumption by stage, and expanding gradually.

Success Metrics

Four metrics for judging whether the workflow is working:

Accumulating these metrics in reports provides evidence for improving the workflow. “The first-pass verification rate rose from 40% to 70%” quantifies the effect of strengthening the development skill's coding guide.

Wrapping Up

This 11-stage pipeline is the result of applying harness-engineering principles—structured context, architectural constraints, and feedback loops—to Jira-driven development automation.

Instead of asking the agent once to “write the code,” design an analysis → generation → verification pipeline as its harness.

Automatically collect context, refine it in stages, verify at every stage, and execute in an isolated environment. Each stage's output becomes the next stage's input. Retry on failure, and hand it to a human if retries cannot resolve it.

Ultimately, building a harness means defining **“what a good development process is”** in code. It turns the analysis → design → implementation → verification flow that human developers followed implicitly into a pipeline an agent can follow explicitly. The essence of software engineering does not change in the AI era. What changes is who carries it out.

References

• Atlassian Jira REST API v2
• Official Git Worktree documentation
• Anthropic — Effective Harnesses for Long-Running Agents
• Harness Engineering: The Developer's New Role in the Age of AI Agents

OpenAI produced a million lines of production code in five months. The amount of application code written directly by a human was zero lines. Three engineers, later seven, built an internal beta product using only Codex agents and merged roughly 1,500 PRs.

What did the human engineers do in this experiment? They did not implement functions or fix bugs. Instead, they designed the repository structure, defined architectural rules, built linters and tests, and, when an agent got stuck, added new tools and constraints rather than rewriting the prompt.

This is **harness engineering**.

Prompt → Context → Harness: Three Stages of Evolution

To understand harness engineering, first look at how our use of AI has evolved.

Prompt engineering optimizes the text instructions sent in a single LLM call. It operates at the level of “Phrasing it this way gets a better answer.”

Context engineering goes one step further. It designs everything inside the context window: documents retrieved through RAG, tool definitions, message history, and memory. The question is how to curate the tokens the model sees.

Harness engineering designs everything outside the agent, from CI pipelines, evaluation loops, and linting rules to observability infrastructure and lifecycle management. It includes prompts and context, but starts from the recognition that those alone are insufficient.

Phil Schmid of Google DeepMind put it this way.

The model is the CPU, and the harness is the operating system. However powerful the CPU, a poorly designed OS limits its performance.

Mitchell Hashimoto, the creator of Terraform, established the term in his February 2026 post, “My AI Adoption Journey.” The central definition is: when AI makes a mistake, go beyond simply fixing it and design guidelines and tools that systematically prevent the same mistake from happening again.

The Three Pillars of a Harness

OpenAI's experiment revealed three core components of a harness.

1. Context Engineering

Structure knowledge inside the repository so the agent can find and read the context it needs for its work.

OpenAI initially created one enormous AGENTS.md file. It failed because it wasted the context window. The team ultimately placed 88 separate AGENTS.md files throughout the repository.

The key principle is to treat AGENTS.md as a table of contents rather than an encyclopedia. Keep it to around 100 lines, and put detailed design documents in docs/. The agent reads the contents and follows them to the documents it needs.

# AGENTS.md (목차 역할, ~100줄)
├── 프로젝트 개요
├── 아키텍처 계층 규칙 → docs/architecture.md
├── 코딩 컨벤션 → docs/conventions.md
├── 테스트 가이드 → docs/testing.md
├── 품질 지표 → docs/quality-scores.md
└── 기술 부채 목록 → docs/tech-debt.md

Knowledge outside the repository—in Slack, Notion, or verbal agreements—is also invisible to the agent. Every important decision and pattern needs to be incorporated into the repository as code or documentation. The repository must become the single source of truth.

2. Architectural Constraints

Mechanically enforce “You must not do this,” rather than merely telling the agent, “Do it this way.”

OpenAI defined strict dependency layers for each business domain.

Types → Config → Repo → Service → Runtime → UI
 
규칙: 상위 레이어는 하위 레이어만 참조할 수 있다.
       UI가 Types를 직접 참조하는 것은 허용되지만,
       Types가 Service를 참조하는 것은 금지된다.

Custom linters and structural tests enforce these rules in CI. PRs that violate them are blocked automatically.

There is another key design choice: the linter's error messages themselves act as repair instructions. The messages are designed so that when an agent encounters a violation, it can read the error and fix it independently.

❌ 기존: "Layer violation detected"
✅ 개선: "Layer violation: Runtime cannot import from UI.
         Move the shared type to Types layer (src/types/).
         See docs/architecture.md#layer-rules for details."

3. Garbage Collection

As agents generate code, they copy bad patterns too, gradually eroding the architecture. OpenAI called this **“AI slop.”**

The solution is not manual cleanup. It is to encode “golden principles” in the repository and let background Codex tasks detect drift and automatically create refactoring PRs. Instead of a human spending every Friday cleaning up technical debt left by AI, another AI cleans it up automatically every day.

A harness is not a one-time setup. It is closer to an operating system that codifies rules and applies them automatically every day.

What a Harness Engineer Actually Does

There are no official job postings with the title “Harness Engineer” yet, but functionally equivalent roles already exist. Here is what the work involves.

Environment Design

Make the repository agent-friendly. Use AGENTS.md as a table of contents and structured docs/ as the source of truth. Version execution plans, design documents, technical debt, and even quality scores inside the repository. The goal is to let the agent work from the repository alone, rather than from knowledge in people's heads.

Tool Design

Carefully design the number, names, and return values of the tools an agent will use. Anthropic outlined the following principles for good agent tools.

A Vercel experiment supports this. After removing 80% of the tools from a text-to-SQL agent and leaving only a single bash execution tool, its success rate rose from 80% to 100%. The number of steps, token use, and response time all fell too.

Constraint Design

Define architectural layers, dependency rules, and type, test, and lint rules, then enforce them through tools. The key is to enforce invariants without micromanaging the implementation. Set the boundaries of what is forbidden and let the agent decide how to implement the rest.

Feedback-Loop Design

Design how the agent responds to test failures, lint errors, and deteriorating observability metrics. Treat every agent failure as a signal to improve the harness. If the agent repeats the same mistake, add a lint rule or test rather than rewriting the prompt.

Memory and Handoffs for Long-Running Agents

Anthropic introduced an initializer-agent pattern for long-running agents.

1. 첫 컨텍스트 윈도우: 초기화 전용 프롬프트로 환경 셋업
2. init.sh 실행, 200개+ 기능 목록 생성 (모두 "failing" 표시)
3. progress 파일(JSON) 생성
4. 새 컨텍스트 윈도우가 열려도 progress 파일을 읽어 작업 이어감
5. git commit 로그로 진행 상황 추적

A key finding: JSON works better than Markdown for feature tracking because agents are less likely to make arbitrary edits to structured data. A harness engineer is effectively building **“an onboarding system for an AI team.”**

Entropy-Reduction Loops

Encode golden principles in the repository and let background agents automatically open quality-check and refactoring PRs. A harness is a continuously operated system, not something configured once and forgotten.

Practical Examples: The Difference a Harness Makes

OpenAI: One Million Lines, Zero Handwritten Code

The central slogan: “Humans steer. Agents execute.” Humans set the direction; agents carry out the work.

Stripe: The Minions System

Stripe's Minions system produces more than 1,000 merged PRs per week. A developer posts a task in Slack, and an agent writes code in an isolated development environment (devbox), gets it through CI, and opens a PR for human review.

It can access more than 400 internal tools through an MCP server, but curates only about 15 tools per session to avoid “token paralysis.” The essence of a harness is providing the right tools, rather than simply providing many.

KRAFTON: The Difference Comes from the Harness

Korea's KRAFTON used its own “Terminus-KIRA” harness to achieve second place worldwide on TerminalBench 2.0 with 74.8% accuracy, just 0.3 percentage points behind OpenAI at 75.1%. It demonstrates that the same model can produce different results depending on the harness.

LangChain: Demonstrating It with a Benchmark

LangChain raised its benchmark score through harness improvements alone, without changing the model.

The key technique is the “reasoning sandwich” pattern: allocate more reasoning compute to planning and verification, and less to implementation. Think deeply; write code quickly.

Anthropic: The Claude Code Harness

It introduced a pattern separating the initializer agent from the coding agent. Even when a fresh context window opens during a long task, progress files and git logs allow the work to continue.

Core Principles

These harness-engineering principles appear across the examples.

The Harness Is the Competitive Advantage

Models are becoming more general-purpose and cheaper. The real differentiation is in the environment where the agent works. The KRAFTON and LangChain examples demonstrate this.

AGENTS.md Is a Map, Not a Manual

Do not try to explain everything in detail. Focus on its role as a table of contents that tells the agent where to find things. OpenAI used 88 separate files instead of one giant AGENTS.md.

Enforce Invariants and Leave the Implementation to the Agent

Linters and tests define only what must not be done. Leave the specific implementation to the agent's discretion. Micromanagement is inefficient whether it happens in the prompt or the harness.

Turn Failures into Assets

An agent's failure is a defect in the harness. Feed failures back into documentation, tests, and tool improvements so the same problem does not recur. Add a new constraint instead of “prompting harder.”

Make the Repository the Single Source of Truth

Agreements in Slack, conventions in Notion, decisions conveyed verbally—the agent cannot see any of them. Everything important must be incorporated into the repository.

Market Trends

AI-Generated Code at Big Tech Companies

The Hiring Market

As of March 2026, there are no job postings titled “Harness Engineer” yet. Functionally equivalent roles are being recruited under titles such as Agentic AI Specialist and AI Infrastructure Engineer. AI engineering positions are growing 300% faster than traditional software engineering roles.

Trends in Korea

**Toss** introduced harness engineering on its technical blog as a mechanism for raising the floor of organizational productivity. Its argument is that LLM use “cannot remain a matter of individual intuition; it must become a system that the team designs and deploys.”

At Korea's first Ralph-ton hackathon, 13 elite developers set up harnesses on the first day, let their agents run autonomously overnight, and reviewed the results the next day. The winning team generated 100,000 lines of code with agents, of which 70,000 were tests.

Limitations and Open Questions

Harness engineering is an interesting direction, but it has its critics.

Thoughtworks described it as a term that was “two weeks old.” It is not yet a standardized official job title. The direction, however, is clear.

Harness Tools and Frameworks

OpenAI designed a JSON-RPC server called Codex App Server to reuse the Codex harness across products. The CLI, VS Code extension, web app, and macOS app all run on the same harness. This shows that harness engineering goes beyond writing new prompts for each app to encompass designing a reusable agent execution environment.

What You Can Do Now

An article on Martin Fowler's site asked whether harnesses will become **“the new service templates.”** Just as teams spin up new services through golden paths today, tomorrow they may choose from a harness catalog bundling custom linters, structural tests, AGENTS.md, and cleanup agents.

You do not need to build a grand system all at once. Here are things you can start doing now.

1. Write AGENTS.md (or CLAUDE.md)—summarize the repository's structure, rules, and main patterns in no more than 100 lines
2. Make linter errors agent-friendly—include how to fix the problem, rather than just saying there is a violation
3. Break work into verifiable units—split tasks into small units whose success or failure can be determined through tests
4. Document agent failures—when a failure repeats, add a constraint instead of another prompt
5. Move knowledge into the repository—document conventions and decisions that exist only in Slack or Notion under docs/

Wrapping Up

The central thesis of harness engineering is simple.

As models become increasingly general-purpose, the harness determines whether an agent succeeds or fails.

The ability to design an environment where agents produce correct code is becoming more important than writing clean code yourself. From writing code to enabling agents to work: that shift in the developer's role has already begun.

References

• OpenAI - Harness Engineering
• Mitchell Hashimoto - My AI Adoption Journey
• Martin Fowler - Harness Engineering
• LangChain - Improving Deep Agents with Harness Engineering
• Anthropic - Effective Harnesses for Long-Running Agents
• Toss technical blog: Improving team productivity through harnesses

Claude Code CLI is powerful. Code reviews, document generation, and even bug fixes take just one terminal command. The drawback is that a person still has to enter that command every time.

What if it could check JIRA issues at 8 every morning, ask Claude to analyze any new ones, and stop on its own when token usage gets too high?

AIForge is the system I built to solve that problem: a web dashboard for running Claude Code CLI unattended through cron scheduling and JIRA issue polling.

GitHub: nasodev/claude-aiforge

What Kind of System Is It?

AIForge is a FastAPI-based web application with three core features.

Technology Stack

Architecture

The system consists of four layers.

┌─ FastAPI Web Server (:8010)
│  ├─ Routes (Dashboard, Projects, Schedules, Executions, Settings, Logs)
│  ├─ Jinja2 Templates (SSR 다크 테마 UI)
│  └─ Static Assets (CSS, Icons)
│
├─ APScheduler (AsyncIO)
│  ├─ System Jobs (토큰 체크, 로그 모니터링)
│  └─ Project Schedules (크론 기반 실행)
│
├─ Services Layer
│  ├─ Executor (async/sync 모드 Claude CLI 실행)
│  ├─ Log Checker (PID 모니터링, 로그 파싱)
│  └─ Scheduler (Job 등록 및 생명주기 관리)
│
└─ SQLite Database (WAL mode)
   ├─ projects
   ├─ schedules
   ├─ executions
   └─ settings

The key design principle is using Claude CLI as a general-purpose executor. Instead of building a separate JIRA API client, it handles JIRA searches and tasks through Claude CLI and browser automation with --chrome.

Data Model

Four tables manage the entire system's state.

CREATE TABLE IF NOT EXISTS projects (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    name TEXT NOT NULL,
    type TEXT NOT NULL CHECK (type IN ('jira', 'schedule')),
    description TEXT,
    jira_search_conditions TEXT,  -- JIRA 타입일 때 검색 조건
    enabled INTEGER DEFAULT 1,
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);
 
CREATE TABLE IF NOT EXISTS schedules (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    project_id INTEGER NOT NULL,
    name TEXT NOT NULL,
    prompt_template TEXT NOT NULL,  -- Claude에게 보낼 프롬프트
    work_dir TEXT NOT NULL,         -- Claude CLI 작업 디렉토리
    cron_expr TEXT NOT NULL,        -- 5-field 크론 표현식
    status TEXT DEFAULT 'idle'
        CHECK (status IN ('idle', 'running', 'paused', 'error')),
    FOREIGN KEY (project_id) REFERENCES projects(id) ON DELETE CASCADE
);
 
CREATE TABLE IF NOT EXISTS executions (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    schedule_id INTEGER NOT NULL,
    pid INTEGER,               -- OS 프로세스 ID
    status TEXT DEFAULT 'running'
        CHECK (status IN ('running', 'success', 'error', 'timeout', 'killed')),
    command TEXT,               -- 실행된 CLI 명령어
    issue_key TEXT,             -- JIRA 이슈 키 (있는 경우)
    log_path TEXT,              -- Claude 로컬 로그 경로
    duration_seconds INTEGER,
    FOREIGN KEY (schedule_id) REFERENCES schedules(id) ON DELETE CASCADE
);

The relationships are simple: Project → Schedules → Executions. CASCADE DELETE cleans up all child data when a project is deleted.

Two Execution Modes

AIForge runs Claude CLI in two modes, depending on the task.

Fire-and-Forget (Asynchronous Mode)

This is for project work. It launches Claude CLI as a subprocess, records only the PID, and returns immediately.

async def execute_async(
    prompt: str,
    work_dir: str,
    issue_key: str | None = None
) -> dict:
    """Fire-and-forget 실행. PID 기록 후 즉시 반환."""
    env = os.environ.copy()
    env.pop("CLAUDECODE", None)  # 재귀 실행 방지
 
    cmd = [
        "claude", "--chrome",
        "--dangerously-skip-permissions",
        "-p", prompt
    ]
 
    process = await asyncio.create_subprocess_exec(
        *cmd,
        cwd=work_dir,
        env=env,
        stdout=asyncio.subprocess.PIPE,
        stderr=asyncio.subprocess.PIPE,
    )
 
    return {"pid": process.pid, "status": "running"}

Removing the CLAUDECODE environment variable is essential. Otherwise, Claude CLI recognizes that it has been invoked inside itself, causing a recursive-execution problem.

Synchronous Mode

This is for system tasks whose results need immediate parsing, such as checking token usage and polling JIRA issues.

async def execute_sync(
    prompt: str,
    work_dir: str,
    timeout: int = 180
) -> dict:
    """동기 실행. 결과를 JSON으로 파싱하여 반환."""
    # ... subprocess 실행 ...
 
    stdout, stderr = await asyncio.wait_for(
        process.communicate(), timeout=timeout
    )
 
    # 3단계 JSON 파싱 폴백
    result = stdout.decode()
    try:
        return json.loads(result)           # 1. 순수 JSON
    except json.JSONDecodeError:
        # 2. ```json ... ``` 마크다운 블록에서 추출
        match = re.search(r'```json\s*(.*?)\s*```', result, re.DOTALL)
        if match:
            return json.loads(match.group(1))
        # 3. { ... } 객체 리터럴에서 추출
        match = re.search(r'\{.*\}', result, re.DOTALL)
        if match:
            return json.loads(match.group(0))

Claude's output is not always clean JSON, so extraction uses three fallbacks: plain JSON, a Markdown code block, and then an object literal.

JIRA Integration: Through the Browser, Without the API

JIRA integrations usually use its REST API. But authentication for the company's JIRA is complex, and configuring API permissions is cumbersome.

AIForge takes a different approach: manipulating JIRA directly through Claude CLI and Chrome browser automation.

1. 크론 트리거 → 스케줄 실행
2. 토큰 한도 체크
3. Claude 동기 실행: "다음 조건에 해당하는 JIRA 검색 해줘 {conditions}"
4. JSON 파싱 → 이슈 키 목록 추출
5. 이슈별로:
   - 이미 실행 중인지 확인
   - prompt_template에서 {issue_key} 치환
   - Claude CLI 비동기 실행
   - PID 기록
6. 백그라운드 로그 체커가 완료 모니터링

The JIRA search prompt is structured as follows:

poll_prompt = (
    f"다음 조건에 해당하는 JIRA 검색 해줘 {conditions} "
    "조회해서 json 으로 알려줘 출력에 다른값은 넣지 않고 json 만 넣어줘"
)

The format Claude returns:

[{"key": "FAS-130"}, {"key": "FAS-131"}]

The advantage is that JIRA API authentication does not need to be configured. If the browser is already logged in, that session is used as it is.

Token Management

Claude Code has usage limits. AIForge checks token usage periodically and automatically pauses work when it approaches a limit.

1. 시스템 잡 (기본 60분 간격)
2. Claude 동기 실행: "claude.ai/settings/usage 접속해서 사용량 확인"
3. 세션 사용률 / 주간 사용률 파싱
4. settings 테이블에 상태 저장
5. 한도 초과 시 → 모든 프로젝트 자동 일시정지

These settings are easy to change in the UI.

token_check_config = {
    "enabled": True,
    "interval_minutes": 60,
    "session_limit_percent": 80,   # 세션 사용량 80% 이상이면 정지
    "weekly_limit_percent": 90     # 주간 사용량 90% 이상이면 정지
}

Background Log Monitoring

How do we know when a fire-and-forget Claude CLI process has finished? A background log checker checks it periodically.

async def check_running_executions():
    """실행 중인 모든 작업의 상태를 확인한다."""
    running = await get_running_executions()
 
    for execution in running:
        pid = execution["pid"]
 
        # PID가 아직 살아있는지 확인
        if not psutil.pid_exists(pid):
            # 프로세스가 종료됨 → 로그 파일 분석
            log_content = await read_log_file(execution["log_path"])
 
            if has_error_pattern(log_content):
                await update_execution_status(execution["id"], "error")
            else:
                await update_execution_status(execution["id"], "success")
 
            # 실행 시간 계산 및 스케줄 상태 업데이트
            await update_schedule_status(execution["schedule_id"], "idle")

It uses psutil to check whether the PID exists. This is lighter than continuously polling stdout and can monitor hundreds of concurrent runs without difficulty.

The Settings System: Separating Config from Status

A key design choice is to divide settings data into two categories.

# Config 키 - 사용자가 변경
CONFIG_KEYS = ["token_check_config", "log_monitor_config", "global"]
 
# Status 키 - 시스템이 업데이트
STATUS_KEYS = ["token_check_status", "log_monitor_status"]

Changing Config automatically reloads APScheduler. For example, changing the token-check interval from 60 minutes to 30 removes the existing job and registers it again with the new interval.

Web Dashboard UI

The whole system is managed through a dark-themed, server-rendered web UI.

Information visible at a glance on the dashboard:

• Total project count and active status
• Number of running tasks
• Recent execution results (success/failure)
• Token utilization (session/weekly)

From Startup to Execution: The Full Flow

When the server starts, initialization proceeds in this order.

run.py (uvicorn 엔트리)
  ↓
app.main:lifespan (FastAPI lifespan)
  ├─ init_db()
  │  ├─ schema.sql 읽기
  │  ├─ 테이블 생성 (없으면)
  │  └─ 기본 설정값 삽입
  │
  └─ init_scheduler()
     ├─ _register_system_jobs()
     │  ├─ 로그 모니터 (interval)
     │  └─ 토큰 체크 (interval)
     │
     └─ _register_project_schedules()
        └─ DB에서 활성 스케줄 로드
           └─ APScheduler 크론 잡으로 등록

A Practical Scenario: Automated Daily Code Reviews

1. Create a project: type=schedule, name="daily-review"
2. Set the schedule: cron=0 8 * * 1-5 (8 a.m. on weekdays)
3. Write the prompt: “Review recent code changes and organize the findings by team”
4. Working directory: /home/dev/project-alpha

At 8 a.m. on Monday:

1. APScheduler triggers the job
2. Token usage is checked synchronously
3. Proceed if session usage is below 80% of the limit
4. Run claude --chrome -p "최근 코드 변경사항을..." asynchronously
5. Record the PID in the executions table
6. Schedule status → running
7. The log checker checks the PID every 10 minutes
8. On completion → execution status=success; the schedule returns to idle

Automated JIRA Issue Processing

1. Create a project: type=jira, search criteria="Project=FAS AND Status=Pending"
2. Set the schedule: cron=*/30 * * * * (every 30 minutes)
3. Prompt template: “Analyze issue {issue_key} and write a proposed solution as a comment”

Every 30 minutes:

1. Claude searches JIRA for matching issues
2. Return [{"key": "FAS-130"}, {"key": "FAS-131"}]
3. Substitute each issue key into the prompt and run asynchronously
4. Skip issues already being processed

Project Structure

aiforge/
├── run.py                    # uvicorn 엔트리포인트
├── schema.sql                # DB 스키마
├── requirements.txt          # Python 의존성
│
├── app/
│   ├── main.py               # FastAPI 앱, lifespan, 라우트 등록
│   ├── database.py           # SQLite 헬퍼, 설정 관리
│   │
│   ├── services/
│   │   ├── scheduler.py      # APScheduler, 실행 로직 (352 LOC)
│   │   ├── executor.py       # Claude CLI 서브프로세스 관리 (200 LOC)
│   │   └── log_checker.py    # PID 모니터링, 로그 파싱 (124 LOC)
│   │
│   ├── routes/
│   │   ├── dashboard.py      # 대시보드 통계
│   │   ├── projects.py       # 프로젝트 CRUD
│   │   ├── schedules.py      # 스케줄 CRUD + 수동 실행
│   │   ├── executions.py     # 실행 이력
│   │   ├── settings.py       # 설정 관리
│   │   ├── logs.py           # 로그 리포트
│   │   └── templates.py      # 워크스페이스 템플릿
│   │
│   └── templates/            # Jinja2 HTML 템플릿 (11개)
│
└── docs/
    ├── ARCHITECTURE.md
    └── PROJECT_ANALYSIS.md

The total codebase is about 1,600 LOC. The whole service fits into that amount of code because it uses Claude CLI as a general-purpose executor. There is no need to implement a separate JIRA client, web-scraping logic, and so on.

Design Decisions and Trade-offs

Why Use Claude CLI as a General-Purpose Executor?

Calling the JIRA REST API directly requires authentication setup (OAuth or API tokens) and response-parsing logic. Claude CLI with the --chrome flag can reuse the browser's existing logged-in session.

There are downsides. It is slower than an API, and Claude's responses are not always predictable. But the core goal of this automation system is unattended operation, not speed. An extra 10 seconds compared with an API is not a problem for a poll that runs once every 30 minutes.

PID-Based Status Tracking

Instead of watching stdout continuously, check only whether the PID exists.

• Advantage: low resource consumption, even with hundreds of concurrent runs.
• Disadvantage: no real-time progress information. Success or failure is determined only after completion.

Choosing SQLite

I chose SQLite instead of an external database such as PostgreSQL or Redis. WAL mode supports concurrent reads and writes, and there is no separate DB server to manage. SQLite is sufficient for a system running on one machine.

How to Run It

# 의존성 설치
pip install -r requirements.txt
 
# 실행
python run.py
# 또는
uvicorn app.main:app --host 0.0.0.0 --port 8010 --reload

Open http://localhost:8010 in a browser to access the dashboard.

Cautions: Claude Code CLI must be installed on the system. Chrome is also required because the system uses the --chrome flag. It includes --dangerously-skip-permissions, so it should be used only on a trusted network.

Limitations and Future Plans

The current version is v0.1.0 and has several limitations.

These limitations are intentional, however. The core goal is unattended Claude Code automation on a single machine, and the current structure is sufficient for that purpose.

Wrapping Up

AIForge's core idea is simple: schedule Claude Code CLI like cron. I added JIRA issue polling, token management, and execution monitoring to create an unattended automation system.

All of this fits into 1,600 lines of Python because Claude CLI is already a powerful executor. JIRA searches, token-usage checks, and code reviews can all be delegated to Claude through prompts. AIForge is the wrapper that makes those instructions run automatically, repeatedly, and without a human present.

Automation in the AI era is less about writing complex code and more about sending the right instructions to AI at the right time. AIForge is my first attempt at that.

Ten is manageable, a hundred is difficult, and tens of thousands is impossible. The previous manual process looked like this.

대시보드 확인 → 이슈 열람 → 분석 → 수정 → 테스트 → PR → 리뷰

It was hard to tell who was handling which issue, the depth of analysis and quality of fixes varied by person, and two people sometimes worked on the same issue simultaneously. Neither the reasoning behind a fix nor the analysis process was recorded.

So I built a system in which AI agents take one issue at a time and run the entire pipeline.

Source code: github.com/nasodev/claude-sonarcube-workflow

The Core Idea

Use Google Sheets as a work queue, with Claude Code subagents taking issues one by one and running the entire pipeline.

SonarQube API → Google Sheets(작업 대기열) → Claude Code 서브에이전트 × 5 병렬
                     ↕                              ↓
              여러 담당자가 배정           분석 → 리뷰 → 개발 → 리뷰 → 테스트 → 완료
                                                    ↓
                                          8단계 리포트 + SQLite 추적 DB

During the design, I borrowed patterns from tools I was already using.

Plugin Architecture

Directory Structure

claude-plugin-sonar/
├── .claude-plugin/plugin.json      # 플러그인 매니페스트
├── settings.json                   # 보안 정책 + 이벤트 훅
├── .env.example                    # 환경 설정 템플릿
├── guides/                         # 에이전트 행동 규칙
│   ├── bash-execution-rules.md     # Bash 실행 9대 원칙
│   └── red-flags.md                # 에이전트 일탈 방지 9대 규칙
├── hooks/
│   └── save-history.sh             # 디버그 모드 대화 기록 저장
├── skills/                         # 7개 스킬 (마이크로서비스 구조)
│   ├── sonar/                      # 오케스트레이터 (유일한 진입점)
│   ├── sonar-intake/               # 이슈 수집
│   ├── sonar-analyze/              # 분석 + Jira/리포트 생성
│   ├── sonar-develop/              # 코드 수정 + TDD
│   ├── sonar-review/               # 독립 검증 에이전트
│   ├── sonar-common/               # 공유 라이브러리
│   └── sonar-dashboard/            # HTML 대시보드 생성
└── data/                           # SonarQube JSON 캐시

The Roles of the Seven Skills

Workflow: The Journey of One Issue

Command Flow

# 1단계: 이슈 수집
/sonar intake
 
# 2단계: 이슈 배정
/sonar claim 5                  # 개인에게 N개 배정
/sonar claim --distribute       # 팀 멤버에게 균등 분배
 
# 3단계: 자동 처리 (담당 이슈 전체 병렬, MAX_CONCURRENT_AGENTS 제어)
/sonar run

State Machine

대기 → CLAIMED → ANALYZING ⟷ REVIEW_ANALYSIS → JIRA_CREATED
                    ↓ (4회 실패)
                 BLOCKED

JIRA_CREATED → DEVELOPING ⟷ REVIEW_FIX → TESTING → DONE
                   ↓ (4회 실패)
                BLOCKED

Every transition generates a report, updates the spreadsheet status in real time, and leaves an execution record in the SQLite tracking database.

Data Flow Between Skills

sonar (오케스트레이터)
  │
  ├─ sonar-intake → SonarQube API 이슈 수집 → Google Sheets 업로드
  │
  ├─ sonar-analyze → 01_analysis_report.md / 03_jira_created.md
  │
  ├─ sonar-review("analysis") → 02_analysis_review.md (PASS/FAIL)
  │
  ├─ sonar-develop → 04_fix_report.md / 06_test_report.md / 07_final_deliverable.md / 08_cto_approval.md
  │
  └─ sonar-review("fix") → 05_fix_review.md (PASS/FAIL)

Core Design: Controlling AI Agents

An Independent Review Agent

The analyzing agent ≠ the verifying agent

sonar-analyze → 01_analysis_report.md → sonar-review (별개의 서브에이전트)
                                              ↓
                                        PASS → 다음 단계
                                        FAIL → 피드백 반영 후 재시도 (최대 3회)
                                        4회 실패 → BLOCKED (사람 개입)

Code changes follow the same structure. When sonar-develop makes a change, sonar-review verifies it independently.

Technical Blocks (settings.json)

Block dangerous agent actions at the system level.

{
  "permissions": {
    "deny": [
      "Bash(git commit*)",
      "Bash(git push*)",
      "Bash(gh pr create*)",
      "Bash(git worktree remove*)",
      "Bash(rm -rf *)",
      "Bash(git reset --hard*)"
    ]
  }
}

AI prepares the deliverables; a human executes them.

Red Flags: Nine Rules to Prevent Agent Deviations

Every rule includes a “plausible excuse versus reality” comparison.

TDD Gating

Writing tests for every issue is inefficient. The analysis stage decides whether TDD is needed.

The Characterization-Test Pattern

1. 수정 전 동작을 캡처하는 테스트 작성
2. BEFORE 실행 → GREEN 확인 (현재 동작 보존 검증)
3. 코드 수정
4. AFTER 실행 → GREEN 확인 (기존 동작 미파괴 검증)

The key: test against “current behavior,” rather than “ideal behavior.” The goal is to improve code quality, not change existing logic.

The Eight-Stage Report Chain

Processing one issue creates eight report files.

reports/{issue_key}/
├── 01_analysis_report.md     ← 근본 원인 분석, 해결 방안, TDD 판정
├── 02_analysis_review.md     ← 독립 에이전트의 분석 검증 (PASS/FAIL)
├── 03_jira_created.md        ← Jira 티켓 생성 확인
├── 04_fix_report.md          ← 수정 내역, 변경 파일, 사이드이펙트
├── 05_fix_review.md          ← 독립 에이전트의 수정 검증 (PASS/FAIL)
├── 06_test_report.md         ← 테스트 실행 결과
├── 07_final_deliverable.md   ← 커밋 메시지 + PR 설명 (복사용)
└── 08_cto_approval.md        ← 전체 과정 종합, 승인 요청

07_final_deliverable.md looks like this.

## 커밋 메시지 (복사용)
fix(UserService): Remove unused parameter 'name' from validateEmail
- Removed unused parameter flagged by SonarQube rule java:S1172
- No behavioral changes, verified by characterization tests
Issue: ODIN-123
 
## PR 설명 (복사용)
...

A human reviews the report and, if they agree, copies the commit message and creates the commit and PR.

Collaboration Through Google Sheets

Concurrent Work by Multiple People

Method 1: Individual claims—each assignee takes as many issues as they want.

담당자 A: /sonar claim 10  → 10개 이슈 배정 → /sonar run
담당자 B: /sonar claim 5   →  5개 이슈 배정 → /sonar run
담당자 C: /sonar claim 20  → 20개 이슈 배정 → /sonar run

Method 2: Even distribution—assign all pending issues to the team at once.

/sonar claim --distribute                          # TEAM_MEMBERS 환경변수 사용
/sonar claim --distribute --members "A,B,C"        # 멤버 직접 지정

Sort by severity (BLOCKER → HIGH → MEDIUM → LOW → INFO), then assign round-robin. With 10 issues and 3 people, A gets 4, B gets 3, and C gets 3.

Leader Assigns, Team Members Execute

리더 (1회)
  1. /sonar intake              ← SonarQube → Sheets 수집
  2. /sonar claim --distribute  ← 심각도 순 라운드로빈 분배
         ↓
  Google Sheets (SSOT)
  3,000개 이슈 / 상태: CLAIMED / 담당자 자동 배정 완료
         ↓
  A: 1,000개 / B: 1,000개 / C: 1,000개

팀원 각자 (동시)
  팀원 A: /sonar run → 서브에이전트 ×5 병렬 → 분석 → 리뷰 → 개발 → 테스트
  팀원 B: /sonar run → 서브에이전트 ×5 병렬 → 분석 → 리뷰 → 개발 → 테스트
  팀원 C: /sonar run → 서브에이전트 ×5 병렬 → 분석 → 리뷰 → 개발 → 테스트
         ↓
  3,000개 이슈 처리 완료 → reports/ + worktrees/

The leader prepares things with two commands; each team member needs only /sonar run.

• Google Sheets = Single Source of Truth (central state store)
• See who is working on which issue in real time
• Each assignee runs independently in their local environment
• Process with up to 5 subagents in parallel

Git Worktree Isolation

worktrees/
├── ODIN-123/    ← 이슈 1 (담당자 A) — fix/ODIN-123 브랜치
├── ODIN-124/    ← 이슈 2 (담당자 A) — fix/ODIN-124 브랜치
├── ODIN-125/    ← 이슈 3 (담당자 B) — fix/ODIN-125 브랜치

Each issue is worked on in an independent branch, so they do not interfere with one another.

Tracking and Analysis: SQLite + Dashboard

SQLite Tracking Database

-- 이슈별 실행 추적
issue_executions: execution_id, issue_key, phase, status, attempt_number, duration_ms, error_message
 
-- 상태 전이 감사 로그
state_transitions: issue_key, from_status, to_status, triggered_by, notes
 
-- 에러 누적 기록
error_log: issue_key, phase, error_type, error_message, review_suggestions

Automatic State Tracking

_STATUS_AUTO_TRACKING = {
    'ANALYZING':      ('start', 'analyze'),
    'JIRA_CREATED':   ('complete', 'analyze', 'success'),
    'DEVELOPING':     ('start', 'develop'),
    'DONE':           ('complete', 'develop', 'success'),
    'BLOCKED':        ('complete_all', 'blocked'),
}

Spreadsheet status changes are recorded automatically in SQLite.

HTML Dashboard

/sonar-dashboard

Visualize KPIs such as success rates, average time per stage, error patterns, and issue timelines.

Project-Specific Specialization

Injecting Coding Rules

CODING_RULES_PATH=/path/to/project-rules

project-rules/
├── SKILL.md              ← 핵심 규칙 개요
├── references/            ← 상세 가이드 (architecture.md, patterns.md, testing.md)
├── templates/             ← 코드 패턴 예시 (service.java, controller.java)
└── scripts/               ← 유틸리티 (linter.sh, formatter.sh)

Project A uses Spring Boot conventions; project B uses Node.js patterns. sonar-develop loads and follows the rules before modifying code.

Jira Mode / Report Mode

Debug Mode

When .env sets DEBUG_MODE=true:

history/{issue_key}/
├── 20250205_143000_subagent_general-purpose.jsonl  ← 원본 트랜스크립트
├── 20250205_143000_summary.md                       ← 요약 리포트
└── 20250205_143000_hook_metadata.json               ← 메타데이터

Claude Code hooks automatically save the records on Stop and SubagentStop events.

Nine Principles for Bash Execution

A Practical Scenario

Assume 3 projects, 3,000 issues, and 5 assignees.

# 1. 이슈 수집
/sonar intake project-a
/sonar intake project-b
/sonar intake project-c
 
# 2. 담당자별 배정
/sonar claim --distribute --members "A,B,C,D,E"
 
# 3. 자동 처리
/sonar run
 
# 4. 현황 확인
/sonar status
 
# 5. 완료 이슈 승인
/sonar approve ODIN-123
 
# 6. 수동 커밋 & PR (07_final_deliverable.md 참조)
git add . && git commit -m "복사한 커밋 메시지"
gh pr create --title "제목" --body "복사한 PR 설명"

Summary

Technology Stack

“Let AI do what AI can do, and humans do what only humans can do.”

AI writes the analysis, fixes, tests, and reports. Humans review the reports, commit, open PRs, and give final approval.

Having humans verify AI deliverables is what makes the whole system trustworthy.

What Is Clawdbot?

Clawdbot is a gateway service connecting messaging apps to AI agents. Install it on a server, and you can send messages through Telegram or similar apps to talk to AI.

A name change is underway: because the similar name causes confusion with Claude, it is being renamed “moltbot.” The installation-script URL has also changed to molt.bot.

• Official site: https://clawd.bot/

Benefits for Claude Subscribers

If you are on a Claude Pro or Max plan, you can use free tokens by linking your account, without an API key.

I use the Max plan, so after linking my account I used Opus 4.5.

Installation

1. Run the Installation Script

Install it on an Ubuntu server with a single command.

curl -fsSL https://molt.bot/install.sh | bash

Node.js 22 or later is required.

2. Onboard and Register the Service

# 온보딩 + systemd 서비스 설치
clawdbot onboard --install-daemon

3. Check the Version

clawdbot --version
# 예시: 2026.1.24-3

Connecting a Telegram Bot

1. Create a Telegram Bot

1. Talk to @BotFather on Telegram
2. Create a new bot with /newbot
3. Choose a name for the bot and obtain its token

2. Register the Token with Clawdbot

# 텔레그램 채널 연동
clawdbot channels login

Enter the token for the Telegram bot you created.

3. Approve Pairing

Send /start to the Telegram bot to receive a code. Enter that code in Clawdbot to complete pairing.

clawdbot pairing approve telegram <페어링코드>

4. Check the Connection

# 상태 확인
clawdbot status
 
# TUI로 테스트
clawdbot tui

Troubleshooting: Gateway Connection Problems

Symptoms

After connecting Telegram, the gateway connection in clawdbot tui kept disconnecting and reconnecting.

gateway disconnected
gateway connected
gateway disconnected
...

I checked with clawdbot status and restarted it using clawdbot gateway stop / clawdbot gateway start, but it would work briefly and then disconnect again.

Diagnosing the Cause

The logs showed an error in Node.js when sending a message to Telegram.

journalctl --user -u clawdbot-gateway.service -n 200 --no-pager

The error was a failed connection to api.telegram.org. Searching Reddit pointed to a DNS/IPv6 issue: Node.js was trying the IPv6 address first and timing out.

The Fix

I forced the Telegram API server's IPv4 address in /etc/hosts.

sudo vim /etc/hosts

Add the following:

149.154.166.110 api.telegram.org

This bypasses DNS resolution and always connects over IPv4.

More About the Cause

Caution: hardcoding an IP can cause problems again if Telegram's infrastructure changes. A more fundamental solution is to fix the DNS settings or configure Node.js to prefer IPv4.

# Node.js IPv4 우선 옵션
NODE_OPTIONS=--dns-result-order=ipv4first

Accessing the Dashboard

The Clawdbot dashboard is accessible only from localhost. If installed on a remote server, access it through an SSH tunnel.

1. Connect the SSH Tunnel

ssh -N -L 18789:127.0.0.1:18789 user@서버IP

2. Find the Dashboard URL

Run the following command on the server to get the URL containing the token.

clawdbot dashboard
# 출력 예시: http://localhost:18789/?token=baf8...

3. Open It in a Browser

With the SSH tunnel connected, open that URL to view the dashboard.

The dashboard makes it easy to manage cron jobs, skill settings, and more.

Ways to Use It

Claude Code's web version lets you give development instructions from your phone while away and connect to GitHub. Clawdbot lets you do similar work in a local environment.

Through Telegram, you can check Docker container status, monitor the server, run simple scripts, and more.

Security Precautions

Clawdbot has broad access to computer resources. Security needs particular attention.

1. Scope of Permissions

Clawdbot can access all resources on the server where it is installed.

An incorrect prompt could lead to unwanted emails or payments.

2. Be Careful with the Skill Marketplace

Skills that have not yet been verified may appear in the marketplace.

Recommendations:

• Install only verified skills
• Check skill source code
• On important servers, isolate it under a separate account

Useful Commands

# 상태 확인
clawdbot status
 
# 게이트웨이 재시작
clawdbot gateway stop
clawdbot gateway start
 
# 환경 점검 및 자동 수리
clawdbot doctor --repair
 
# TUI 실행
clawdbot tui
 
# 대시보드 URL 확인
clawdbot dashboard
 
# 페어링 승인
clawdbot pairing approve telegram <코드>

Wrapping Up

Clawdbot lets you talk to an AI agent and manage your server through Telegram anytime, anywhere.

Many developers are using it, so updates are arriving quickly. Still, security and permission management require attention.

• Official site: https://clawd.bot/
• Official documentation: https://docs.clawd.bot

Migration Targets

Previous Architecture

서버에서 직접 실행:
git pull → pip install / npm install → alembic upgrade → systemctl restart

New Architecture

GitHub Actions에서 빌드:
테스트 → Docker 이미지 빌드 → GHCR push → 서버에서 pull → 실행

Why Move to Docker?

1. Unify Different Development Environments

With Docker, the same container image runs in every environment.

2. Prepare for Infrastructure Growth

Current setup:

• PostgreSQL (DB)

Planned additions:

• RabbitMQ / Redis (Message Queue)
• MinIO / S3 (Object Storage)
• Other services

Docker Compose makes adding and removing services straightforward.

3. Improve Security

기존: 소스 폴더 내 .env 파일
      └─ git에 실수로 커밋될 위험

변경: /home/funq/config/서비스명/.env.prod
      └─ 소스와 완전 분리, 서버에만 존재

4. Comparison with the Previous Approach

Moving PostgreSQL to Docker

Before converting FastAPI to Docker, I first moved the on-premises PostgreSQL 16 installation into Docker.

Before and After

Migration Procedure

1. Back Up the Database

sudo -u postgres pg_dumpall > /tmp/pg_backup_all.sql

2. Configure Docker Compose

/home/funq/dev/infra/postgres/docker-compose.yml:

services:
  postgres:
    image: postgres:16
    container_name: postgres
    restart: unless-stopped
    environment:
      POSTGRES_USER: postgres
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
      POSTGRES_DB: postgres
      TZ: Asia/Seoul
    ports:
      - "5432:5432"
    volumes:
      - postgres_data:/var/lib/postgresql/data
      - ./init:/docker-entrypoint-initdb.d
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U postgres"]
      interval: 10s
      timeout: 5s
      retries: 5
 
volumes:
  postgres_data:

3. Set Environment Variables

echo "POSTGRES_PASSWORD=your_password" > .env

4. Stop and Disable the Existing PostgreSQL Service

sudo systemctl stop postgresql
sudo systemctl disable postgresql

5. Start the Docker Container

cd /home/funq/dev/infra/postgres
docker compose up -d

6. Restore the Data

# 백업 파일 복사
cp /tmp/pg_backup_all.sql ./init/01_restore.sql
 
# 비표준 명령어 제거 (pg_dumpall 출력에 포함된 경우)
sed -i '/^\\restrict/d; /^\\unrestrict/d' ./init/01_restore.sql
 
# 수동 복원 (볼륨이 이미 초기화된 경우)
docker exec -i postgres psql -U postgres < ./init/01_restore.sql

7. Verify the Restore

# 데이터베이스 목록 확인
docker exec postgres psql -U postgres -c "\l"

Dockerfile & Docker Compose

Docker Concepts

Dockerfile = 요리 레시피
Docker Image = 완성된 요리 (냉동 보관)
Docker Container = 요리를 데워서 서빙한 상태 (실행 중)

Dockerfile (Multi-stage Build)

# Stage 1: 빌드 단계 - 의존성 설치
FROM python:3.12-slim AS builder
WORKDIR /app
RUN apt-get update && apt-get install -y gcc libpq-dev
COPY requirements.txt .
RUN pip install --no-cache-dir --user -r requirements.txt
 
# Stage 2: 프로덕션 - 최소 런타임
FROM python:3.12-slim AS production
WORKDIR /app
RUN apt-get update && apt-get install -y libpq5 curl \
    && useradd --create-home appuser
COPY --from=builder /root/.local /home/appuser/.local
COPY --chown=appuser:appuser app/ ./app/
COPY --chown=appuser:appuser alembic/ ./alembic/
USER appuser
CMD ["uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "8000"]
 
# Stage 3: 개발 - 테스트 도구 포함
FROM production AS development
USER root
RUN pip install pytest pytest-cov pytest-asyncio httpx
USER appuser
CMD ["uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "8000", "--reload"]

Benefits of a Multi-stage Build:

• Build tools such as gcc from the builder stage are excluded from the final image
• Smaller image (~800MB → ~300MB)
• Improved security (runs as a non-root user)

Multi-stage Build Structure

┌─────────────────────────────────────────────────────────────┐
│ Stage 1: builder                                            │
│ ┌─────────────────────────────────────────────────────────┐ │
│ │ Python 3.12-slim                                        │ │
│ │ + gcc (C 컴파일러)        ← 빌드에만 필요               │ │
│ │ + libpq-dev (개발 헤더)   ← 빌드에만 필요               │ │
│ │ + pip 패키지들                                          │ │
│ └─────────────────────────────────────────────────────────┘ │
│                            │                                 │
│                    패키지만 복사                             │
│                            ▼                                 │
│ Stage 2: production                                         │
│ ┌─────────────────────────────────────────────────────────┐ │
│ │ Python 3.12-slim (깨끗한 상태)                          │ │
│ │ + libpq5 (런타임 라이브러리만)                          │ │
│ │ + pip 패키지들 (builder에서 복사)                       │ │
│ │ + 소스 코드                                             │ │
│ │                                                         │ │
│ │ gcc 없음! libpq-dev 없음! → 이미지 크기 감소            │ │
│ └─────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────┘

Docker Compose Configuration

Development (docker-compose.yml):

services:
  backend-api:
    build:
      context: .
      target: development    # 개발 단계 사용
    ports:
      - "28000:8000"         # 로컬:컨테이너 포트 매핑
    volumes:
      - ./app:/app/app:ro    # 코드 변경 시 즉시 반영
    environment:
      - DATABASE_URL=postgresql://postgres:postgres@postgres:5432/backend_api
    networks:
      - funq-network

Production (docker-compose.prod.yml):

services:
  backend-api:
    image: ghcr.io/nasodev/backend-api:${IMAGE_TAG:-latest}
    ports:
      - "127.0.0.1:8000:8000"  # Nginx 프록시만 접근 가능
    env_file:
      - /home/funq/config/backend-api/.env.prod
    deploy:
      resources:
        limits:
          memory: 512M
    logging:
      options:
        max-size: "10m"
        max-file: "3"

Differences Between Development and Production:

Docker Network

# 네트워크 생성
docker network create funq-network
 
# PostgreSQL 컨테이너 연결
docker network connect funq-network postgres

Containers must be on the same network to communicate by container name.

┌─────────────────────────────────────┐
│           funq-network              │
│                                     │
│  backend-api  ←──→  postgres        │
│  (FastAPI)          (PostgreSQL)    │
└─────────────────────────────────────┘

GHCR & GitHub Actions CI/CD

What Is GHCR?

GHCR = GitHub Container Registry
     = GitHub이 제공하는 Docker 이미지 저장소

It serves a similar purpose to Docker Hub:

Why Use GHCR?

Previous Approach (Without GHCR):

개발자 PC에서 코드 작성
       ↓
GitHub에 push
       ↓
서버에서 git pull
       ↓
서버에서 docker build  ← 서버 리소스 사용, 느림
       ↓
docker compose up

With GHCR:

개발자 PC에서 코드 작성
       ↓
GitHub에 push
       ↓
GitHub Actions에서 docker build  ← GitHub 서버가 빌드 (무료)
       ↓
빌드된 이미지를 GHCR에 저장
       ↓
서버에서 이미지만 pull  ← 빌드 없이 다운로드만
       ↓
docker compose up

Benefit: the server only downloads an image that has already been built → fast, with no build load on the server

The Full Flow

┌──────────────────────────────────────────────────────────────┐
│                     GitHub Actions                            │
│                                                               │
│  ┌─────────┐      ┌─────────────┐      ┌─────────┐          │
│  │  test   │ ───→ │ build-push  │ ───→ │ deploy  │          │
│  └─────────┘      └─────────────┘      └─────────┘          │
│                          │                   │               │
│                          ▼                   │               │
│                   ┌───────────┐              │               │
│                   │   GHCR    │              │               │
│                   │ (이미지   │              │               │
│                   │  저장소)  │              │               │
│                   └───────────┘              │               │
└──────────────────────────────────────────────│───────────────┘
                          │                    │
                          │         SSH로 서버에 접속
                          │                    │
                          ▼                    ▼
┌─────────────────────────────────────────────────────────────┐
│                    Production Server                         │
│                                                              │
│   docker pull ghcr.io/nasodev/backend-api:latest            │
│          ↓                                                   │
│   docker compose up -d                                       │
│                                                              │
└─────────────────────────────────────────────────────────────┘

GitHub Actions Configuration

jobs:
  # 1단계: 테스트
  test:
    runs-on: ubuntu-latest
    steps:
      - run: pytest tests/ -v
 
  # 2단계: 이미지 빌드 & GHCR 푸시
  build-and-push:
    needs: test
    steps:
      - uses: docker/login-action@v3
        with:
          registry: ghcr.io
          username: ${{ github.actor }}
          password: ${{ secrets.GITHUB_TOKEN }}
 
      - uses: docker/build-push-action@v5
        with:
          push: true
          tags: ghcr.io/nasodev/backend-api:latest
 
  # 3단계: 서버 배포
  deploy:
    needs: build-and-push
    steps:
      - name: SSH로 배포
        uses: appleboy/ssh-action@v1.0.3
        with:
          host: ${{ secrets.SSH_HOST }}
          username: ${{ secrets.SSH_USER }}
          key: ${{ secrets.SSH_KEY }}
          script: |
            echo "${{ secrets.GHCR_TOKEN }}" | docker login ghcr.io -u nasodev --password-stdin
            docker pull ghcr.io/nasodev/backend-api:latest
            docker compose -f docker-compose.prod.yml up -d

Setting Up a PAT (Personal Access Token)

Authentication is required to pull images from GHCR.

How to Create a PAT:

1. GitHub → Settings → Developer settings → Personal access tokens
2. Create a token with read:packages permission
3. Register it as GHCR_TOKEN in GitHub Actions Secrets

Image Tag Strategy

tags: |
  type=sha,prefix=       # 커밋 SHA (예: abc1234)
  type=raw,value=latest  # 항상 latest

Result:

ghcr.io/nasodev/backend-api:latest   ← 최신 버전
ghcr.io/nasodev/backend-api:abc1234  ← 특정 커밋 버전

If a rollback is needed:

docker pull ghcr.io/nasodev/backend-api:abc1234
docker compose up -d

Operations Commands

Check Status

docker ps
docker logs backend-api
curl http://localhost:8000/health

Restart

docker compose -f docker-compose.prod.yml restart

Roll Back

# 이전 버전으로 롤백
export IMAGE_TAG=abc1234
docker compose -f docker-compose.prod.yml up -d

View Logs

# 실시간 로그
docker logs -f backend-api
 
# 최근 100줄
docker logs --tail 100 backend-api

Clean Up Disk Space

docker system prune -a  # 미사용 이미지/컨테이너 정리

File Structure

# PostgreSQL (infra 저장소)
/home/funq/dev/infra/postgres/
├── docker-compose.yml
├── .env
├── .env.example
└── init/
    └── 01_restore.sql

# Backend API
backend-api/
├── Dockerfile              # 멀티 스테이지 빌드 설정
├── .dockerignore           # 빌드 제외 파일
├── docker-compose.yml      # 개발 환경
├── docker-compose.prod.yml # 프로덕션 환경
├── deploy/
│   └── docker-setup.sh     # 서버 초기 설정 스크립트
├── run-local.sh            # 로컬 실행 스크립트
└── .github/
    └── workflows/
        └── deploy.yml      # CI/CD 파이프라인

Conclusion

Benefits gained from moving to Docker:

1. Faster deployment: just pull an image, without pip install
2. Consistent environments: the local and server environments match
3. Easy rollbacks: recover immediately with an earlier image tag
4. Resource management: memory and CPU limits improve stability
5. Log management: automatic rotation keeps disk usage under control
6. Simpler DB management: manage PostgreSQL as a container too

The initial setup is complex, but once it is in place, operations become much easier.

At first, I wrote shell scripts and put prompts telling Claude to run them in .md files. Pasting them into Claude Code ran the scripts and produced good results.

In an IDE such as Cursor, pasting prompts into split terminal panes was convenient. Warp, which I use these days, is a terminal with an attached editor, so copying prompts from files was awkward. Converting them to slash commands seemed likely to solve that too.

While I was at it, I thought I might as well turn all my Git tasks into commands: branch creation, commits, pushes, PRs, and merges. Automating the whole workflow seemed like something that would pay off later.

But once there were seven commands, managing them became difficult. Copying them into every project was cumbersome too.

So I made a plugin.

The Finished Result

# Marketplace 추가
/plugin marketplace add nasodev/nasodev-marketplace
 
# 플러그인 설치
/plugin install git-workflow@nasodev-marketplace

Installing it adds seven slash commands:

I numbered them in workflow order so it would be clear what to do first.

Why a Plugin?

Initially, I just placed the command files in the project's .claude/commands/ directory.

.claude/commands/
├── git-branch.md
├── git-commit.md
└── git-push.md

That worked, but had problems:

1. Copying into every project—copy the files whenever a new project starts
2. Cumbersome updates—copy scripts back into all projects whenever they change
3. No version tracking—no clear record of which project has which version

With a plugin:

# 한 번만 설치하면 모든 프로젝트에서 사용
/plugin install git-workflow@nasodev-marketplace
 
# 업데이트도 한 줄
/plugin update git-workflow@nasodev-marketplace

Plugin Structure

A Claude Code plugin is simpler than you might expect.

claude-git-workflow/
├── .claude-plugin/
│   └── plugin.json          # 플러그인 메타데이터
├── commands/
│   ├── git:0.check.md       # 슬래시 커맨드 정의
│   ├── git:1.branch.md
│   └── ...
├── scripts/
│   ├── git-check.sh         # 실제 실행될 스크립트
│   ├── git-branch.sh
│   └── ...
└── README.md

plugin.json

{
  "name": "git-workflow",
  "description": "Git workflow automation with interactive scripts",
  "version": "1.3.0",
  "author": {
    "name": "nasodev",
    "email": "creationand2017@gmail.com"
  },
  "repository": "https://github.com/nasodev/claude-git-workflow",
  "license": "MIT"
}

Command File (git:0.check.md)

---
name: git:0.check
description: "Git 상태 확인 (isolated fork)"
context: fork
allowed-tools: [Bash]
model: haiku
---
 
# Git 상태 및 설정 확인
 
현재 저장소의 브랜치, 사용자 설정, 작업 상태를 확인한다.
 
---
 
**반드시 Bash tool로 아래 스크립트를 실행해라. 다른 방법은 허용하지 않는다.**
 
\`\`\`bash
./scripts/git-check.sh
\`\`\`

Two key points:

1. Frontmatter: isolated execution requires context: fork along with name, allowed-tools, and model
2. Explicit instructions: “Always execute the script with the Bash tool.” Without this, Claude sometimes explains the script instead of running it

Why a Marketplace Is Needed

The plugin is built—how do I distribute it?

Claude Code uses a marketplace-based plugin system.

# 이렇게 직접 설치 불가
/plugin install nasodev/claude-git-workflow  # 에러

Plugins can be installed only through a marketplace:

# 1. Marketplace 등록
/plugin marketplace add nasodev/nasodev-marketplace
 
# 2. 그 다음에 설치 가능
/plugin install git-workflow@nasodev-marketplace

Marketplace Structure

A marketplace is also a GitHub repository:

nasodev-marketplace/
├── .claude-plugin/
│   └── marketplace.json     # 플러그인 목록
├── README.md
└── LICENSE

marketplace.json

{
  "name": "nasodev-marketplace",
  "owner": {
    "name": "nasodev",
    "email": "creationand2017@gmail.com"
  },
  "metadata": {
    "description": "Claude Code plugins by nasodev",
    "version": "1.0.0"
  },
  "plugins": [
    {
      "name": "git-workflow",
      "description": "Git workflow automation with interactive scripts",
      "version": "1.3.0",
      "source": {
        "source": "url",
        "url": "https://github.com/nasodev/claude-git-workflow.git"
      }
    }
  ]
}

Add the plugin to the plugins array to make it installable by users.

Script Highlights

git-check.sh: Current Status at a Glance

./scripts/git-check.sh

Running it shows the following:

• Repository: name, path, and remote URL
• Branch: current branch, default branch, and ahead/behind status
• User Configuration: local, global, and effective settings
• Working Directory: counts of staged, unstaged, and untracked files
• Recent Commits: the five most recent commits

Showing Local vs Global user settings together is particularly useful for avoiding the question, “Whose name will this commit use?”

git-push.sh: Linting Across Languages

It runs lint checks automatically before pushing:

# 프로젝트 타입 자동 감지
if [ -f "package.json" ]; then
    npm run lint
elif [ -f "pyproject.toml" ]; then
    ruff check .  # 또는 pylint
elif [ -f "go.mod" ]; then
    go vet ./...
elif [ -f "Cargo.toml" ]; then
    cargo clippy
fi

It detects Node.js, Python, Go, Rust, and Java projects and runs the appropriate linter.

git-branch.sh: Safe Branch Creation

# 변경사항이 있으면 자동 stash
git stash push -m "Auto stash before branch switch"
 
# 브랜치 생성
git checkout -b feature/new-feature
 
# stash 복원
git stash pop

It switches branches safely even when there are uncommitted changes.

Context Isolation: context: fork

Running the commands repeatedly exposed a problem. After /git:0.check and then /git:3.commit, the previous conversation context kept accumulating. That wasted tokens, and sometimes the commands referred to earlier results and behaved unexpectedly.

With context: fork, the command runs in an isolated context:

---
name: git:0.check
description: "Git 상태 확인 (isolated fork)"
context: fork
allowed-tools: [Bash]
model: haiku
---

Required Fields

A few additional fields are needed for context: fork to work:

Including only description and context: fork does not provide isolation. name, allowed-tools, and model must also be present for “(forked execution)” to appear and actual isolation to occur.

Choosing a Model

Not every command needs the same model:

haiku is fast and inexpensive, making it suitable for commands that only need to run a script.

sonnet is used to write commit messages or PR descriptions. A stronger model is needed to create meaningful messages in Korean.

opus is used when complex analysis or judgment is needed. It suits advanced tasks such as code review and architectural design.

Testing Installation

Let's install it:

# 터미널에서
claude plugin marketplace add nasodev/nasodev-marketplace
# ✔ Successfully added marketplace: nasodev-marketplace
 
claude plugin install git-workflow@nasodev-marketplace
# ✔ Successfully installed plugin: git-workflow@nasodev-marketplace
 
claude plugin list
# ❯ git-workflow@nasodev-marketplace
#   Version: 1.3.0
#   Scope: user
#   Status: ✔ enabled

Restart Claude Code after installation to use the /git: commands.

Installation Scopes

Plugins can be installed in three scopes:

# 글로벌 설치 (기본값)
claude plugin install git-workflow@nasodev-marketplace
 
# 프로젝트별 설치
claude plugin install -s project git-workflow@nasodev-marketplace

Since the default is user, installing once makes /git:* commands available in any project.

GitHub Repositories

• Plugin: https://github.com/nasodev/claude-git-workflow
• Marketplace: https://github.com/nasodev/nasodev-marketplace

Wrapping Up

Claude Code plugins are easier to build than I expected.

1. In commands/, create .md files
2. Write .claude-plugin/plugin.json
3. Create a marketplace repository and register the plugin

Then you can use it as /my-command in every project.

If you have a recurring workflow, try turning it into a plugin.

So I decided to build a simple tablet timer that starts and stops when you touch anywhere on the screen. Making it a PWA would let us add it to the home screen, use it like an app, and run it offline.

Demo: cupstacking.funq.kr

Technology Stack

1. A requestAnimationFrame-Based Timer

The Limitations of setInterval

// ❌ 부정확한 방식
setInterval(() => {
  setTime(prev => prev + 10);
}, 10);

setInterval does not guarantee precise intervals. It is throttled when the browser tab goes into the background, and callback execution time accumulates, causing drift.

requestAnimationFrame + Date.now()

export type TimerState = 'idle' | 'running' | 'stopped';
 
export function useTimer() {
  const [time, setTime] = useState(0);
  const [state, setState] = useState<TimerState>('idle');
  const startTimeRef = useRef<number>(0);
  const rafRef = useRef<number>(0);
 
  useEffect(() => {
    if (state !== 'running') return;
 
    const updateTime = () => {
      const elapsed = Date.now() - startTimeRef.current;
      setTime(elapsed);
      rafRef.current = requestAnimationFrame(updateTime);
    };
 
    rafRef.current = requestAnimationFrame(updateTime);
 
    return () => {
      cancelAnimationFrame(rafRef.current);
    };
  }, [state]);
 
  const start = useCallback(() => {
    startTimeRef.current = Date.now();
    setState('running');
  }, []);
 
  const stop = useCallback(() => {
    cancelAnimationFrame(rafRef.current);
    const finalTime = Date.now() - startTimeRef.current;
    setTime(finalTime);
    setState('stopped');
    return finalTime;
  }, []);
 
  const reset = useCallback(() => {
    cancelAnimationFrame(rafRef.current);
    setTime(0);
    setState('idle');
  }, []);
 
  const toggle = useCallback(() => {
    if (state === 'idle') {
      start();
      return null;
    } else if (state === 'running') {
      return stop();
    }
    return null;
  }, [state, start, stop]);
 
  return { time, state, start, stop, reset, toggle };
}

Key points:

• Calculate elapsed time from Date.now() → no cumulative timing error
• requestAnimationFrame → synchronized with the display refresh rate, usually 60fps
• Store the start time in useRef → unaffected by rerenders
• toggle() → handle start and stop in one function, returning the final time on stop

Formatting Time

export function formatTime(ms: number): string {
  const seconds = Math.floor(ms / 1000);
  const milliseconds = ms % 1000;
  return `${seconds}.${milliseconds.toString().padStart(3, '0')}`;
}
// 12345 → "12.345"

2. A Complete Guide to PWA (Progressive Web App)

PWA technology lets an app built with web technologies be used like a native app. Here is why I applied it to this timer:

1. Home-screen installation—launch immediately by tapping an icon
2. Full screen—looks like an app without the browser address bar
3. Offline support—works without internet access
4. Automatic updates—new deployments are applied automatically

Configuring vite-plugin-pwa

import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'
import tailwindcss from '@tailwindcss/vite'
import { VitePWA } from 'vite-plugin-pwa'
 
export default defineConfig({
  plugins: [
    react(),
    tailwindcss(),
    VitePWA({
      registerType: 'autoUpdate',
      includeAssets: ['favicon.ico', 'apple-touch-icon.png'],
      manifest: {
        name: '컵쌓기 타이머',
        short_name: '컵타이머',
        description: '스포츠 스태킹 타이머 앱',
        theme_color: '#10b981',
        background_color: '#ffffff',
        display: 'standalone',
        orientation: 'portrait',
        icons: [
          {
            src: 'pwa-192x192.png',
            sizes: '192x192',
            type: 'image/png'
          },
          {
            src: 'pwa-512x512.png',
            sizes: '512x512',
            type: 'image/png'
          }
        ]
      }
    })
  ],
})

Manifest Properties

Comparing Display Modes

┌─────────────────────────────────────────────────────┐
│  fullscreen   │  standalone   │    browser         │
├───────────────┼───────────────┼────────────────────┤
│  상태바 숨김    │  상태바만 표시  │  브라우저 UI 전체   │
│  게임/몰입형    │  일반 앱       │  웹사이트          │
│  주소창 없음    │  주소창 없음    │  주소창 있음        │
└─────────────────────────────────────────────────────┘

Why I chose standalone: it shows the status bar, including the clock and battery, while hiding the browser UI.

registerType: autoUpdate

registerType: 'autoUpdate'

Service Worker update strategies:

Why I chose autoUpdate: there is little concern about losing state in this timer app, and it is better to always use the latest version.

Preparing Icons

A PWA needs at least two icons:

public/
├── apple-touch-icon.png  # iOS Safari용 (180x180)
├── favicon.ico           # 브라우저 탭용
├── pwa-192x192.png       # Android 홈 화면용
└── pwa-512x512.png       # 스플래시 화면용

Generate them automatically from the source SVG using sharp:

import sharp from 'sharp';
 
const sizes = [192, 512];
const svgBuffer = await fs.readFile('public/icon.svg');
 
for (const size of sizes) {
  await sharp(svgBuffer)
    .resize(size, size)
    .png()
    .toFile(`public/pwa-${size}x${size}.png`);
}

Supporting iOS Safari

On iOS, specify apple-touch-icon separately:

<link rel="apple-touch-icon" href="/apple-touch-icon.png" />
<meta name="apple-mobile-web-app-capable" content="yes" />
<meta name="apple-mobile-web-app-status-bar-style" content="default" />

Build Output

Files generated automatically when npm run build runs:

dist/
├── sw.js              # Service Worker
├── workbox-*.js       # Workbox 런타임
├── manifest.webmanifest
└── registerSW.js      # SW 등록 스크립트

3. Preventing Duplicate Touch and Click Events

On mobile, a touchend is followed by a click event after a 300ms delay. If both are handled, the timer toggles twice.

const touchHandledRef = useRef(false);
 
const handleTouchEnd = useCallback(
  (e: React.TouchEvent) => {
    e.preventDefault();
    touchHandledRef.current = true;
    handleTouch();
    setTimeout(() => {
      touchHandledRef.current = false;
    }, 300);
  },
  [handleTouch]
);
 
const handleClick = useCallback(() => {
  if (touchHandledRef.current) return; // 터치 후 클릭 무시
  handleTouch();
}, [handleTouch]);

<div
  className={`min-h-full ${bgColor} flex flex-col`}
  onClick={handleClick}
  onTouchEnd={handleTouchEnd}
>

Event flow:

1. Touch → touchHandledRef = true → toggle the timer
2. Click within 300ms → check touchHandledRef → ignore
3. After 300ms → touchHandledRef = false → wait for the next input

4. A Custom LocalStorage Hook Pattern

Managing Players and Records

const PLAYERS_KEY = 'cupstacking_players';
const RECORDS_KEY = 'cupstacking_records';
 
function generateId(): string {
  return Date.now().toString(36) + Math.random().toString(36).substr(2);
}
 
export function usePlayers() {
  const [players, setPlayers] = useState<Player[]>(() => {
    const stored = localStorage.getItem(PLAYERS_KEY);
    return stored ? JSON.parse(stored) : [];
  });
 
  useEffect(() => {
    localStorage.setItem(PLAYERS_KEY, JSON.stringify(players));
  }, [players]);
 
  const addPlayer = useCallback((name: string): Player => {
    const newPlayer: Player = {
      id: generateId(),
      name: name.trim(),
      createdAt: Date.now(),
    };
    setPlayers((prev) => [...prev, newPlayer]);
    return newPlayer;
  }, []);
 
  const removePlayer = useCallback((id: string) => {
    setPlayers((prev) => prev.filter((p) => p.id !== id));
  }, []);
 
  const getPlayer = useCallback(
    (id: string) => players.find((p) => p.id === id),
    [players]
  );
 
  return { players, addPlayer, removePlayer, getPlayer };
}