DEV Community: zxpmail

From Shackles to Anchors: How I Resurrected an Abandoned Open-Source Framework

zxpmail — Sat, 06 Jun 2026 12:06:06 +0000

From Shackles to Anchors: How I Resurrected an Abandoned Open-Source Framework by Learning to Work With AI, Not Against It

GitHub Finish-Up-A-Thon submission

The Abandoned Framework

ReqForge is an open-source LLM agent harness — a structured workflow for turning product ideas into shippable code. I started it months ago. It worked, but something was off.

The framework was built on a simple philosophy: constrain the model enough and it will produce correct code. Rules. Validators. Checklists. Gates. Every conversation started with a list of "don'ts" — don't over-abstract, don't hallucinate APIs, don't write empty catch blocks, don't use as any, don't copy-paste templates...

I had built a framework that spent most of its energy fighting the model. And the result was predictable: generated code was correct but stiff. Every new feature required more rules. The framework was becoming a burden.

I shelved it.

The Spark

Then I watched a YouTube video about a 2300-year-old Chinese philosophy text — Zhuangzi's story of Cook Ding, a butcher whose knife never dulls.

Lord Wenhui watches Cook Ding cut up an ox. Other butchers smash through bones, replacing their knife every month. But Ding's blade glides through the ox's body like music. After thousands of oxen, his knife is still sharp.

"How?" asks the lord.

Ding replies: "What I care about is the Way, which goes beyond skill. A good butcher changes his knife every year. An ordinary butcher changes it every month. I've used this knife for 19 years. When I first started, I saw nothing but the whole ox. After three years, I no longer saw the ox — I saw the gaps between joints. Now I meet it with spirit, not with my eyes. My senses stop. My spirit guides the knife."

I realized: my framework was stuck at "good butcher" level. I was adding better rules, sharper validators, more gates — better knives — instead of learning to see the gaps.

The gaps are the model's natural pattern-matching ability. LLMs aren't logic engines. They're pattern matchers. Every "don't" rule forces the model to suppress its natural generation pattern. Instead of fighting this, I should work with it.

The Resurrection: From Shackles to Anchors

I reopened the repo and completely rewrote the design philosophy.

Before (Shackles)

The framework's code generation guidance looked like this:

Checklist:
- [ ] No over-abstraction
- [ ] No hallucinated APIs
- [ ] No hardcoded values
- [ ] No empty catch blocks
- [ ] No copy-paste templates
- [ ] No fake tests
- [ ] No TODO debris
- [ ] No type escapes
- [ ] No style scattering

Nine "don't" rules. The model had to recite them while generating, suppressing its natural tendencies simultaneously. Every suppression could fail.

After (Anchors)

I replaced the checklist with three short code examples — perfect patterns showing the model what TO do:

// Anchor 1: Error handling pattern
async function createUser(email: string, password: string): Promise<User> {
  const existing = await db.user.findUnique({ where: { email } });
  if (existing) {
    throw new AppError(ErrorCode.CONFLICT, "Email already registered");
  }
  const hashed = await bcrypt.hash(password, 12);
  const user = await db.user.create({ data: { email, passwordHash: hashed } });
  logger.info("User created", { userId: user.id });
  return user;
}

(Plus API endpoint and test pattern anchors.)

The model reads three perfect examples, its pattern-matching activates, and it naturally continues in the correct style. The checklist stays as a safety net — demoted from generation guide to pre-delivery sanity check.

The Full Transformation

I made eight interconnected changes in one continuous session with GitHub Copilot:

Change	Before	After
Difficulty markers	Every task treated equally	🔴/🟡/🟢 levels — model slows down for hard tasks, speeds through easy ones
Anti-slop reform	9 "don't" rules per skill	3 perfect code anchors + light checklist
Phase 1 catalyst	First phase starts coding immediately	Lays down domain skeleton first — all subsequent code follows
Self-review	Code reviewed externally (late)	Self-review in the same hot context (early)
Closing ritual	Phase ends, move to next	Append discoveries to spec, log decisions, clear context
Attention layout	Key info buried in the middle	Critical instructions at the end (recency bias)
Auto-rollback	Manual git checkout	Automatic snapshot restore on verify failure
Security rules	Scattered across files	One installable template

I also wrote a benchmark to prove the approach works — same task, two approaches, measured results:

Dimension	Old (9 rules)	New (3 anchors)
Tests passed	26/26	26/26
Code size	53 lines	45 lines (−15%)
Structure	2-pass filter + Map	1-pass filter, simpler

And a manifesto explaining the philosophy — From Shackles to Anchors.

How GitHub Copilot Made This Possible

This wasn't a "write 1000 lines of boilerplate" session. It was something more interesting.

The most valuable Copilot interactions weren't code completions — they were discussions about design philosophy. I pasted a Chinese subtitle file about Zhuangzi into the conversation. Copilot connected it to LLM harness design. We iterated on the "2.5 layer" concept together — not as master and tool, but as two collaborators refining an idea.

Copilot didn't just generate code. It:

Challenged my assumptions — when I proposed adding more rules, it pointed out I was building a "good butcher's knife"
Connected disparate ideas — Zhuangzi's butcher 🠒 Transformer pattern matching 🠒 anchor-based guidance
Generated the code changes — all 8 framework modifications implemented in one continuous session
Wrote the benchmark — created the reproducible comparison test
Drafted the philosophy document — translated Chinese insights into English

The final framework has 236 files in sync across 4 AI client adapters, all 98 unit tests pass, and the generated code is measurably cleaner. But the real transformation was in the design philosophy.

The Result

The project went from an abandoned rule-collection to a coherent, philosophy-driven framework with:

4 AI client adapters (Claude Code, Cursor, OpenCode, Gemini CLI)
13 skills with anchor-based guidance
10 sub-agents for specialized tasks
4 project starter templates for forge-scaffold init
944 files in perfect sync across all adapters
98 unit tests, all passing
A published design manifesto with benchmark evidence
A GitHub Issue explaining the philosophy

More importantly, the framework no longer fights the model. It works with it.

Less Is More: Why 3 Code Examples Beat 10 Rules for LLM Code Generation

zxpmail — Sat, 06 Jun 2026 11:55:06 +0000

A controlled benchmark comparing two approaches to guiding LLM code generation.

The Question

Most LLM harnesses guide code generation via rules: "Don't hardcode API keys." "Don't use empty catch blocks." "Don't over-abstract."

But LLMs aren't logic engines. They're pattern matchers. Every "don't" rule adds cognitive load — the model must actively suppress its natural generation pattern while simultaneously constructing code.

What if we flipped the approach? Instead of telling the model what NOT to do, give it 3 perfect examples of what TO do. Let its pattern-matching do the work.

Does it matter? I ran a controlled test to find out.

The Setup

Project: todo-cli — a simple CLI todo list tool (Node.js + TypeScript, 6 source files, 5 test files).

Task: Add a search command with:

Keyword search (case insensitive)
Optional --category filter
Grouped output matching existing style
5 test cases covering normal, empty, filtered, case-insensitive, and error scenarios

Two approaches:

Approach	Context given to LLM
OLD (rules)	9-item "don't" checklist (no over-abstraction, no hallucinated APIs, no empty catches, etc.)
NEW (anchors)	3 short code snippets showing the project's error handling pattern, API endpoint pattern, and test pattern + 4-item safety checklist

Both received the exact same task definition. Both were implemented in the same environment. Both passed the same test suite.

The Results

Dimension	OLD (9 rules)	NEW (3 anchors)
Tests passed	26/26	26/26
Code size	53 lines	45 lines (−15%)
Filter logic	2-step filter + pre-built Map	1-step filter
Naming	`trimmedKeyword.toLowerCase()` called each iteration	`lowerKeyword` extracted once
Type safety	plain `string`	`TodoCategory[]` typed
Extra validation	invalid category check with error message	omitted (simpler)

Both produced functionally identical, fully tested code. The NEW approach produced code that was 15% shorter and structurally simpler.

The Code Difference

Here's the core difference in the search logic:

OLD (rules-guided)

let filtered = todos.filter(t =>
  t.description.toLowerCase().includes(trimmedKeyword.toLowerCase())
);

if (category) {
  const validCategory = CATEGORY_ORDER.includes(category);
  if (!validCategory) {
    console.log(`Invalid category: ${category}`);
    return;
  }
  filtered = filtered.filter(t => t.category === category);
}

// ...then build a grouped Map for output
const grouped: Record<string, typeof todos> = {};
for (const cat of CATEGORY_ORDER) grouped[cat] = [];
for (const todo of filtered) grouped[todo.category]?.push(todo);

The model followed the rules literally: validate everything, check every boundary. The result is safe but verbose — two filter passes + a pre-built Map.

NEW (anchor-guided)

const lowerKeyword = trimmed.toLowerCase();

const filtered = todos.filter(t => {
  const matchesKeyword = t.description.toLowerCase().includes(lowerKeyword);
  if (!category) return matchesKeyword;
  return matchesKeyword && t.category === category;
});

// ...group via runtime filter (matching list.ts style)
for (const cat of CATEGORY_ORDER) {
  const items = filtered.filter(t => t.category === cat);

The model saw the existing list.ts pattern (runtime filter) and naturally followed it. lowerKeyword is extracted once. Category filter is rolled into the same pass. No pre-built Map — same approach the existing codebase uses.

Why This Happens

The 9-rule checklist created a constraint-satisfaction problem: the model had to simultaneously satisfy 9 negative constraints while generating code. Each constraint competes for attention. The result? Conservative code that over-validates.

The 3 anchor examples created a pattern-continuation problem: the model saw three correct examples, recognized the pattern, and continued it. No constraints to satisfy — just a familiar path to follow.

This aligns with how Transformers work:

Pattern matching is what they do best (attention over repeated patterns)
Logical constraint satisfaction is what they do worst (requires combining multiple independent conditions)

What This Doesn't Prove

This is one test, one task, one project. It doesn't prove anchors are universally better.

What it does suggest: the gap between the two approaches is real but not dramatic. At the scale of a single 50-line function, the difference is marginal. At the scale of a 100-file project, a consistent 15% reduction in code volume with no loss in correctness or safety is worth paying attention to.

The full reproducible benchmark (contexts, task definition, generated code) is in the ReqForge repo.

Try It Yourself

The two prompt contexts are checked into the repo:

OLD: benchmark/context-OLD.md
NEW: benchmark/context-NEW.md

Pick a small feature in your own project. Run it twice — once with each context. See if you get the same result.

This benchmark was run as part of the ReqForge project, which implements the "anchor" approach across all 6 of its skills. The full design philosophy is explained in From Shackles to Anchors.

Repository: github.com/zxpmail/ReqForge