In the Japanese tech scene, using Tmux and Claude Code for multi-agent development has become quite the trend. It is undeniably convenient; development velocity has spiked, and the quality of task output is remarkably high compared to before.
However, regardless of how far we go, the reality remains: a significant amount of "cognitive debt" regarding the Agent's output is still being pushed onto the engineer.
Admittedly, using Claude Code with Opus 4.6—leveraging "SuperPower" mode and running multi-agent workflows—allows us to achieve solid results even for complex tasks. My personal experience confirms this.
But for a tech entrepreneur building a business-grade product to provide to clients, being "more convenient" isn't enough.
While development is faster, I don't feel the process for verifying those deliverables has become equally convenient. We need to ensure the code meets the quality, maintenance efficiency, and security standards required for client delivery.
Of course, you can tell an Agent to write test code or perform security audits. But can we truly guarantee the same level of maintainability and verifiability that was naturally achieved back when humans wrote every line of code themselves?
Perhaps there are already SKILLs or Git repositories out there designed to solve these specific concerns. Maybe I just don't know them yet. But if I don't know them, isn't it likely that the majority of people are in the same boat?
My Current Approach
For now, I’ve decided to adopt a classic procedure to verify the quality, maintenance efficiency, and security of Agent-generated code.
Until a vastly superior SKILL or workflow permeates society (or at least the tech industry as a whole), this feels like the right move. It might be a conservative stance, but it provides peace of mind.
Workflow Notes
Here is the process I am currently following:
Step 1: Issuing Tickets
- First, I communicate the issues I'm sensing to the Agent within the working directory. We verbalize my "Intent" and perform verifications against the actual code.
- Based on those results, I convey the desired direction and concerns, having the Agent refine the coding direction and To-Do list.
- Once organized, I have the Agent save these as individual Issue Tickets (.md files). (Yes, very old school.)
The prompt I use for this is as follows:
Please output a report of my QA Intent and the related investigation items
regarding our research so far as a Markdown file in @.qa_session/reports.
Additionally, please save the potential development Issue tickets as
independent files in @.qa_session/issues.
Ensure they are structured so that another Agent can pick them up immediately,
including:
- Background
- Targeted files/locations
- Challenges/Problems
- Proposed solution
- Ideal goal state
- Items requiring user confirmation
Please think deeply and ensure they are developer-friendly.
Step 2: Generating Handover Docs with Low Cognitive Load
After saving the Issue Tickets, I have the Agent generate "Handover Documentation" designed for "cognitive volatility or absence." This ensures a completely fresh AI Agent can pick up the task immediately, or a human can look back later and instantly recall the context to provide proper instructions.
The prompt for this is as follows:
Please establish a mechanism or documentation to minimize the user's cognitive debt.
<Points>
・Enable "Quick Turn Around" when reading back later.
・Determine whether a task can be delegated to an Agent independently (hands-off).
・Identify perspectives or action points to watch out for when delegating tasks.
・Ensure the system can self-update to prevent information volatility when
additional questions or new ISSUES arrive.
</Points>
Implement measures to reduce cognitive debt to the absolute limit.
It should be accessible even to a "plain" Agent with no prior context.
Additionally, include a line (e.g., in a comment) in each ISSUE file
that references this documentation.
I follow this process every time.
The benefits are:
- Context Restoration: Even if I've forgotten what I was doing, the Agent can instantly restore the context from a "plain" state by reading these files.
- Traceability: If a bug appears, I can trace back exactly when and why certain development choices were made.
The resulting output from the prompt looks like this:
Confirming the final configuration.
⏺ Searched for 1 pattern (ctrl+o to expand)
⏺ Completed. Overview of the created Cognitive Debt Reduction Mechanism:
.qa_session/
├── README.md ← 2-minute overview. Reading order guide.
├── AGENT_RUNBOOK.md ← Check before delegating to Agent. Autonomy, pitfalls, and completion criteria.
├── ARCHITECTURE_CONTEXT.md ← Tech map for zero-knowledge starts. Includes self-update rules.
├── reports/
│ └── QA-001_*.md ← Investigation history and rationale.
└── issues/
├── INDEX.md ← Central registry. Delegation-ready column, templates, self-update rules.
└── ISSUE-001 to 007_*.md ← Reference comments added to all entries.
Design choices implemented to reduce cognitive debt:
┌────────────────────────────┬────────────────────────┬──────────────────────────────────────────────────────┐
│ Feature │ Location │ Effect │
├────────────────────────────┼────────────────────────┼──────────────────────────────────────────────────────┤
│ Quick Turn-Around Table │ README.md │ Identifies "what to read" in 2s based on objective. │
├────────────────────────────┼────────────────────────┼──────────────────────────────────────────────────────┤
│ Delegation Readiness Table │ INDEX.md + RUNBOOK.md │ Instant judgment on whether to assign to an Agent. │
├────────────────────────────┼────────────────────────┼──────────────────────────────────────────────────────┤
│ Pitfalls & Exit Criteria │ RUNBOOK.md Section 3 │ Defines "what not to do" and "definition of done." │
├────────────────────────────┼────────────────────────┼──────────────────────────────────────────────────────┤
│ Copy-Paste Templates │ INDEX.md │ Ready to paste immediately when launching an Agent. │
├────────────────────────────┼────────────────────────┼──────────────────────────────────────────────────────┤
│ Glossary │ CONTEXT.md Section 1 │ Prevents Agents from stalling on specific jargon. │
├────────────────────────────┼────────────────────────┼──────────────────────────────────────────────────────┤
│ File Map (Copy-Ready) │ CONTEXT.md Section 2 │ Minimizes time spent searching for file paths. │
├────────────────────────────┼────────────────────────┼──────────────────────────────────────────────────────┤
│ Dual-System Diagram │ CONTEXT.md Section 3 │ Forces understanding of the biggest trap first. │
├────────────────────────────┼────────────────────────┼──────────────────────────────────────────────────────┤
│ Self-Update Rules │ End of each file │ Prevents info decay. Defines update timing/targets. │
├────────────────────────────┼────────────────────────┼──────────────────────────────────────────────────────┤
│ HTML Comment Ref Lines │ Header of all ISSUES │ Ensures navigation to vital docs from any issue. │
└────────────────────────────┴────────────────────────┴──────────────────────────────────────────────────────┘
Summary
My current best practice is to leave behind fact-based intermediate documentation. This ensures that the development is correct, reduces our cognitive debt, and allows for immediate action.
It’s a classic approach, but in the end, it actually makes things easier when delegating tasks like security verification to an AI.
Top comments (0)