Batch File Creation

Batch File Scaffolding (Single-Turn Scripted Generation)

Overview

When an agent initializes a new microservice, UI component directory, or test suite, creating each file through individual write_to_file tool calls requires 10 to 20 consecutive agent turns.

Each turn re-sends the entire conversation transcript, accumulating quadratic token costs and taking 1 to 2 minutes of back-and-forth roundtrips.

The Batch File Scaffolding Protocol enables agents to create 10+ directory structures and boilerplate files in a single turn by writing and executing a local generator script or using a multi-file dictionary writer.

15-Turn Sequential Invocations vs. 1-Turn Batch Scaffolding

┌─────────────────────────────────────────────────────────────┐
│                 Scaffolding Turn Mechanics                  │
│                                                             │
│  Sequential Tool Calls (10 Files):                          │
│  • Turn 1: `write_to_file("Button.tsx")`                    │
│  • Turn 2: `write_to_file("Button.test.tsx")`               │
│  • Turn 3: `write_to_file("Button.module.css")`             │
│  • ... (10 turns, 10 API roundtrips, 15,000 tokens billed) │
│                                                             │
│  Single-Turn Batch Scaffolding (10 Files):                  │
│  • Turn 1: Agent writes & executes `scratch/scaffold.py`   │
│  ↳ All 10 files created on disk simultaneously in 50ms      │
│  ↳ 1 Turn, 1 API roundtrip, 650 tokens billed (95% Savings) │
└─────────────────────────────────────────────────────────────┘

Production Batch Scaffolding Implementations

1. Python Dictionary-Driven Multi-File Writer

Use this pattern to scaffold multiple files across directories in a single command:

# scratch/scaffold_component.py
from pathlib import Path

FILES = {
    "src/components/Modal/Modal.tsx": """import React from 'react';
import styles from './Modal.module.css';

export interface ModalProps {
  isOpen: boolean;
  onClose: () => void;
  title: string;
  children: React.ReactNode;
}

export const Modal: React.FC<ModalProps> = ({ isOpen, onClose, title, children }) => {
  if (!isOpen) return null;
  return (
    <div className={styles.overlay}
      <div className={styles.modal} => e.stopPropagation()}>
        <h2>{title}</h2>
        {children}
      </div>
    </div>
  );
};
""",
    "src/components/Modal/Modal.module.css": """.overlay { position: fixed; inset: 0; background: rgba(0,0,0,0.5); }
.modal { background: #fff; padding: 24px; border-radius: 8px; margin: 100px auto; max-width: 500px; }
""",
    "src/components/Modal/Modal.test.tsx": """import { render, screen } from '@testing-library/react';
import { Modal } from './Modal';

describe('Modal Component', () => {
  it('renders children when isOpen is true', () => {
    render(<Modal isOpen={true} => {}} title="Test"><div>Content</div></Modal>);
    expect(screen.getByText('Content')).toBeInTheDocument();
  });
});
""",
    "src/components/Modal/index.ts": """export { Modal } from './Modal';
export type { ModalProps } from './Modal';
"""
}

for file_path, content in FILES.items():
    p = Path(file_path)
    p.parent.mkdir(parents=True, exist_ok=True)
    p.write_text(content.strip() + "\n", encoding="utf-8")
    print(f"Created: {file_path}")

2. Node.js Script Execution in 1 Shell Command

When working in TypeScript/Node environments, agents can execute a single CLI one-liner via run_command:

node -e "
const fs = require('fs');
const files = {
  'src/types/auth.ts': 'export interface User { id: string; email: string; }',
  'src/constants/routes.ts': 'export const ROUTES = { LOGIN: \"/login\", HOME: \"/\" } as const;',
  'src/lib/jwt.ts': 'export const verifyToken = (token: string) => true;'
};
Object.entries(files).forEach(([p, c]) => {
  fs.mkdirSync(require('path').dirname(p), { recursive: true });
  fs.writeFileSync(p, c);
  console.log('Created: ' + p);
});
"

Turn & Token Benchmark Comparison

Scaffolding a full React component suite (Component, CSS Module, Unit Test, Storybook, Type Definitions, Index re-export):

Agent Operational Directive

MANDATORY: When creating $>2$ related files or scaffolding a new directory module, agents must never execute sequential back-and-forth tool calls. Write a dictionary-based generator script to scratch/ and execute it in a single turn.