diff options
| -rw-r--r-- | CASE_STUDY.md | 79 | ||||
| -rw-r--r-- | README.md | 3 |
2 files changed, 82 insertions, 0 deletions
diff --git a/CASE_STUDY.md b/CASE_STUDY.md new file mode 100644 index 0000000..9930fe8 --- /dev/null +++ b/CASE_STUDY.md @@ -0,0 +1,79 @@ +# Case Study: Building `wg-wrap` with an AI Agent + +## 1. Introduction +`wg-wrap` is a tool for Linux that lets you run specific programs over a WireGuard VPN without needing root privileges or changing your whole computer's network settings. + +This project serves as a case study in how a high-level expert can use an AI agent to accelerate development. The project was created by a **Principal Systems & Security Architect** (an expert in Linux kernel internals, C/Go interop, and security hardening) using the **`pi` agentic harness** and the **Gemma 4 31B** reasoning model. + +--- + +## 2. How the AI was Managed: The Rulebook +To prevent the AI from making common mistakes or writing fragile code, the project used a file called `AGENTS.md`. This served as a set of strict instructions the AI had to follow. + +### Key Rules That Worked: +- **Clear Tool Use**: The rules explained exactly how the AI should read and edit files to avoid mistakes. +- **Stop and Pivot**: If a command failed, the AI was told to stop and try a different approach rather than repeating the same error. +- **Isolated Testing**: The AI had to use temporary folders for tests so it wouldn't interfere with the actual system. + +--- + +## 3. Development Strategy +The project progressed rapidly because the creator applied a specific strategic sequence to reduce technical risk: + +1. **Solving the Hardest Parts First**: The first priority was "Technical Derisking." The focus was on the C launcher and Linux namespaces. Because this was the most difficult part, it was solved before any other features were built. +2. **Steel Thread Proof of Concept**: Once the hard part was solved, the goal was to create a "steel thread"—the shortest possible path to a working end-to-end demonstration. +3. **Security Hardening**: After the tool worked, the focus shifted to security. This included adding fuzzing to find crashes and preventing DNS leaks. +4. **Ergonomics and Usability**: The final phase focused on the user experience, such as creating a standalone binary, removing external dependencies, and refining the CLI. + +--- + +## 4. Timeline Comparison +The project was built in a few concentrated bursts over about three weeks (May 22 – June 13, 2026), totaling approximately **25–30 active hours**. + +### Effort Comparison +Comparing the total hours spent shows the magnitude of the difference in productivity. + +| Scenario | Estimated Total Hours | Comparison to Actual | +| :--- | :--- | :--- | +| **Expert + Agent (Actual)** | **25 - 30 Hours** | **1x** | +| **Expert by Hand** | **80 - 160 Hours** | **~4x - 6x Slower** | +| **Typical Senior + Agent** | **120 - 240 Hours** | **~5x - 8x Slower** | +| **Typical Senior by Hand** | **480 - 960 Hours** | **~16x - 32x Slower** | + +A traditional manual workflow for a typical senior engineer would require 3 to 6 months of full-time effort. The agentic approach, steered by a systems expert, completed the same project in less than one standard work-week of actual effort. + +### Context on "Typical Senior Engineer" +For this comparison, a "typical senior engineer" is defined as someone proficient in Go and general Linux networking (e.g., comfortable with `ip` and `iptables` and building production apps), but who does not have specialized, daily experience in kernel-level namespace manipulation or C-to-Go bootstrap launchers. + +--- + +## 5. Problems Encountered and How They Were Fixed + +### Problem 1: Go doesn't play well with Linux Namespaces +- **The Issue**: The Go language uses multiple threads, which makes it crash when using certain Linux kernel functions (`setns` and `unshare`). +- **The Fix**: A **C launcher** was used. This is a small, single-threaded program that sets up the network environment before the Go program starts. + +### Problem 2: Namespaces disappearing too early +- **The Issue**: The network tunnel would sometimes close while a program was still using it. +- **The Fix**: A **reference counter** was implemented. The system tracks how many programs are using the tunnel and only closes it when the last one exits. + +### Problem 3: Relying on external tools +- **The Issue**: The program originally called the `ip` command to configure the network, which can behave differently on different systems. +- **The Fix**: These calls were replaced with native Go code using a library called `netlink`. + +--- + +## 6. What could be improved? + +### Easier Building +- **The Problem**: Building requires `gcc` and `go` to be configured exactly right. +- **The Fix**: Use a **Docker container** to ensure the code builds the same way for everyone. + +### Better Testing +- **The Problem**: Full tests require a Linux machine with specific permissions, making cloud automation difficult. +- **The Fix**: Use a **virtual machine (QEMU)** to run tests in a controlled environment. + +--- + +## 7. Conclusion +The main lesson from `wg-wrap` is that AI agents are a force multiplier for expertise. While the AI handled the implementation and the "grind" of debugging, the human provided the high-level strategy. By solving the hardest problems first and using an agentic harness to execute precisely, a project that would typically take months was completed in a few days of active work. @@ -90,5 +90,8 @@ make - **Unit & Integration Tests**: `make test` - **Security Fuzzing**: `make fuzz` (tests argument integrity through the bootstrap loop). +### Development & Agentic Workflow +`wg-wrap` was built using an agentic development process. For a detailed analysis of the strategy, the timeline, and the synergy between the human architect and the AI agent, see [CASE_STUDY.md](./CASE_STUDY.md). + ## License This project is free and unencumbered software released into the public domain. See the [LICENSE](LICENSE) file for details. |