SS
Back to posts

I Built "nanj-dev-bu", a Claude Skill for Preserving Design Decisions as Forum Threads

Why I built a Claude Code skill that discusses design topics in a forum-like thread, promotes conclusions into ADRs or specs, makes decision history easier to revisit, and accepts higher token usage as the tradeoff.

Apr 14, 20268 min read
Claude
AI Agent
ADR
Skill

Share this article

TL;DR

  • I built a Claude Code skill called nanj-dev-bu.
  • It records design discussions as forum-like threads, then promotes adopted conclusions into ADRs or specs.
  • The goal is to make it easier to trace who raised which concern, and why a decision was made.
  • The drawback is clear: it uses more tokens than a normal prompt.

What I Built

nanj-dev-bu is a Claude Code skill for running design discussions as forum-like threads.

It does three main things:

  1. Pseudo-members with fixed handles discuss a design topic.
  2. The end of the thread summarizes the conclusion and next actions.
  3. Adopted decisions are promoted into docs/adr/ or specs/.

Threads live under history/threads/. ADRs live under docs/adr/, and canonical specs live under specs/.

When information conflicts, the priority is:

specs/ > docs/adr/ > history/threads/

In other words, the forum-like thread is only the discussion log. The final spec belongs in Spec, and adopted design decisions belong in ADRs.

Why I Built It

When I ask an AI agent for design advice, it can produce a conclusion quickly. But if I stop there, the reason behind the conclusion often becomes thin.

Later, I can end up in situations like these:

  • I cannot remember what alternatives were considered.
  • I cannot tell which concerns we accepted as tradeoffs.
  • A topic that was postponed for future discussion disappears.
  • It feels hard to explain the decision as my own, because I only approved the AI proposal.

What I really want to preserve in design decisions is not just the conclusion. The friction, objections, and rejected alternatives that led to the conclusion are often more useful later.

So I chose a forum-like exchange as a way to keep the decision-making process readable.

A Decision Thread

The following is a reconstructed thread for the article, based on the decisions I made while creating this skill.

# [ai-agent] Meeting: how should we keep design decision logs?

0001 Nanj-PM 2026/04/14 Tue 09:00:12 JST

When we ask an AI agent for design advice, we get a conclusion.
But later, the question "why did we choose this again?" tends to remain.

This time, I want the skill to preserve the decision-making process itself.

---

0002 Type-Safety-Reviewer 2026/04/14 Tue 09:01:34 JST

>>1
If all we need is the conclusion, an ADR is enough.
But ADRs alone tend to lose the temperature of rejected options.

"Option A is easy to implement but may block future expansion."
"Option B is solid but too heavy for the MVP."

If we want to preserve that kind of comparison and hesitation, we need a discussion log first.

---

0003 Observability-Reviewer 2026/04/14 Tue 09:03:02 JST

If we keep logs, the format must be easy to revisit.
A plain long memo makes it hard to tell what was a concern and what was a conclusion.

A forum-like structure separates statements by role, which makes rereading easier.
Fixed perspectives like PM, type safety, SRE, and scope control also help.

---

0004 Scope-Keeper 2026/04/14 Tue 09:04:21 JST

But the style must not become the goal.

This should not be "a skill that creates funny logs."
It should be "a skill that makes design decisions traceable."

The forum style is seasoning.
The canonical sources are ADRs and Specs.
If we reverse that, we only get hard-to-read documentation.

---

0005 Token-Budget-Reviewer 2026/04/14 Tue 09:06:10 JST

Also, token usage will increase.

The moment we make several pseudo-members speak, output volume grows.
The skill also has to read its philosophy, style rules, handles, templates, and ADR policy.

It is heavier than simply asking, "What do you think of this design?"
We should state that drawback clearly.

---

0006 Nanj-PM 2026/04/14 Tue 09:08:45 JST

>>4 >>5
So the operating rules are:

- Do not create threads for minor typos or obvious fixes.
- Use threads only for design decisions, spec changes, technology choices, and other topics where the reason should remain readable later.
- Separate discussion logs, ADRs for adopted decisions, and Specs as canonical behavior.
- Keep the style mild and prioritize readability.
- Accept higher token usage, and narrow where we use it.

---

0007 Type-Safety-Reviewer 2026/04/14 Tue 09:10:03 JST

This shape works.

With the discussion log, we can re-evaluate the decision later.
At the same time, the current source of truth remains in specs/.

Separating process from canonical documents is the key.

---

## Thread Conclusion

- Keep design discussions as forum-like threads under `history/threads/`.
- Promote adopted design decisions into `docs/adr/`.
- Treat `specs/` as the canonical source for current behavior.
- Keep the forum-like style mild, readable, and accurate.
- Token usage increases, so only create threads for topics where the history is worth preserving.

## Next Actions

- Prepare the `nanj-dev-bu` skill templates.
- Define the role of each handle.
- Create one sample thread, ADR, and Spec.

This format makes it easier to see which topics were considered than a simple "we wrote an ADR" record.

Why Use a Forum-Like Format?

I did not choose the forum-like format because I wanted a joke. I chose it because a lighter tone can make design friction easier to surface.

When decisions are written only as polished documents, the conclusion can become too clean. Clean documentation is good, but it often drops traces of hesitation and opposing views.

In a forum-like thread, I use several handles with fixed roles:

  • Nanj-PM: MVP, priority, and scope
  • Type-Safety-Reviewer: types, safety, and responsibility boundaries
  • Nanj-SRE: operations, monitoring, and incident response
  • Observability-Reviewer: logs and traceability
  • Scope-Keeper: narrowing the topic when it spreads too much

Separating perspectives like this prevents the AI from rushing toward one conclusion. It lets the design be shaken from multiple angles.

The important part is the role, not the character. Because the same handle keeps speaking from the same perspective, the discussion axis stays more stable.

Promoting Threads into ADRs and Specs

Threads are easy to revisit, but they are dangerous as canonical specs. They mix ideas under consideration, rejected options, and postponed topics.

So nanj-dev-bu uses this flow:

Design discussion thread
  -> ADR
  -> Spec

Threads expand and compare the topics. ADRs record adopted decisions and reasons. Specs keep only the content that should be referenced as current behavior.

With this separation, readers can choose the right source for their purpose:

  • Read specs/ when implementing.
  • Read docs/adr/ when you want to know why the design exists.
  • Read history/threads/ when you want the original debate and hesitation.

This keeps the discussion history without making the source of truth ambiguous.

What Worked Well

The best part was that it became harder to outsource accountability for decisions to the AI.

When I ask an AI agent to "design this nicely," it returns a plausible answer. But if I adopt it as-is, my sense of ownership over the design gets weaker.

The thread format naturally raises questions like:

  • Is this too heavy for the MVP?
  • How far should we account for future extension?
  • What could hurt us operationally?
  • Which file should be the canonical source?
  • What are we explicitly not doing this time?

When those questions remain as statements in the log, it is easier for me to recover the reasoning later.

It moves the decision from "the AI said so" toward "we chose this after considering these concerns and tradeoffs."

Drawback: High Token Usage

The drawback is token usage. It definitely increases.

There are three reasons:

  1. The skill has to read its premise and rules.
  2. Output grows because the discussion is written as several handles.
  3. When promoting a thread into an ADR or Spec, the prior log has to be referenced.

A normal design question can be short:

For this auth design, should we use JWT or sessions?

With nanj-dev-bu, the process includes separated perspectives, conclusion, next actions, and ADR promotion. That inevitably makes it longer.

So it is not suited for turning every task into a thread. For minor fixes or cases with no real options, it only adds cost.

The countermeasure is to narrow the conditions for creating a thread:

  • Technology selection
  • Data models
  • Authentication and authorization
  • External API integration
  • Operational design
  • Long-lived spec changes

And I avoid it for work like:

  • Typo fixes
  • Simple renames
  • Small additions that follow an existing pattern
  • Formatting changes

Using "will I want to reread the reason later?" as the criterion makes the decision easier.

Summary

nanj-dev-bu is a skill for preserving design discussions with AI agents as forum-like threads.

The goal is not to create entertaining logs. It is to keep the path to the decision, promote adopted conclusions into ADRs or Specs, and make the result explainable later.

On the other hand, token usage definitely increases. That is why it should be used only when the background of a design decision is worth preserving.

In AI-agent-assisted development, there are times when recovering why something was done matters more than building it quickly. I built this as a slightly unusual way to keep that decision history.