AI agents will default to traditional app architecture unless the docs teach the Bitfield translation directly. Give the agent a concrete job, the public names it may use, and the private files it must not import or parse.
You ask an AI agent to add a feature. It creates a store, imports another package, parses a JSON file, or calls an implementation directly. The code may compile, but it trains the app back into the old architecture.The useful output is code that chooses the Bitfield path before the first edit, not code that compiles after recreating the old app shape.The prompt to paste
Build this the Bitfield way.
Do not create a shared mutable app object.
Do not import another package's private store, service, file, or implementation.
Do not make React, Swift, Kotlin, Rust, Python, or any other shell become the coordinator.
Classify the job first:
- shared product fact -> Bitfield state
- data another package made available -> data name
- work another package should run -> action request
- visual-only state -> private UI state
- bytes shipped with a package -> things-to-store-and-run.json
Before editing, state which category each new value or action belongs to.
After editing, report the public data names, action names, package files, private UI state, and tests/checks.
Classification protocol
Before writing code, the agent must fill this out:| Question | Answer format |
|---|
| What product fact is shared? | shared fact: selected-file or none |
| What named data is read? | data name: project-preview-surface or none |
| What work is requested? | action request: selected-agent.update or none |
| What state is visual-only? | private UI state: dropdownOpen, hoveredRow |
| What package material is used? | package bytes: getting-started-help or none |
| What public adapter is used? | React read hook, action request, native shell read, or another public adapter |
| What private file/code is avoided? | no package store imports, no package file parsing, no direct implementation call |
Bad output and corrected output
The shape most agents reach for
The agent reaches for a shared store, direct import, package file read, or framework coordinator because that is what most public examples show.Bad: shared object import
import { fileTreeStore } from '../file-tree/store';
const selected = fileTreeStore.selectedFile;
Read the public value
const selected = readInput('selected-file');
React adapter example
const selected = useBitfieldData<string>('selected-file');
Bad: direct implementation call
import { refreshPreviewStatus } from '../project-preview/refresh';
await refreshPreviewStatus(projectId);
Request the work
await sendRequestToBitfieldTarget({
target: 'project-preview.refresh-status',
payload: { projectId },
});
Bad: consumer parses package files
const boundary = await fetch('/packages/help-package/things-to-store-and-run.json');
Read package output
const help = readInput('getting-started-help');
Bad: every state value becomes global
await writeBitfieldState('hovered-sidebar-row', rowId);
Keep visual state local
const [hoveredRow, setHoveredRow] = useState<string | null>(null);
Bad: React context becomes product architecture
export const ProductContext = createContext({
selectedFile: null,
currentProject: null,
notificationMode: 'normal',
setSelectedAgent() {},
});
Use Runtime Kit names
const selectedFile = useBitfieldData<string>('selected-file');
const currentProject = useBitfieldData<Project>('current-project');
const notificationMode = useBitfieldData<string>('notification-mode');
await sendRequestToBitfieldTarget({
target: 'selected-agent.update',
payload: { agentId },
});
Bad: mixed read and work path
const preview = await refreshPreviewAndReturnGlobalStore(projectStore.current.id);
Split reading from running work
await sendRequestToBitfieldTarget({
target: 'project-preview.refresh-status',
payload: { projectId },
});
const preview = readInput('project-preview-surface');
Review checklist
| Question | Correct answer |
|---|
| Did the agent create a shared app store? | It should not. Use Bitfield state for shared product facts. |
| Did the agent import another package’s private code? | It should not. Use data names or action requests. |
| Did the agent put visual-only UI state in Bitfield? | It should not. Keep visual-only state private. |
Did the agent parse things-to-store-and-run.json from app code? | It should not. Runtime Kit handles package files. |
| Did the agent call implementation code directly? | It should not. Send an action request. |
| Did the agent make React the architecture? | It should not. React is one adapter around Bitfield reads/requests. |
| Did the agent name data and action requests clearly? | It should. Names should describe the real product job. |
Common failures
| Agent phrase | What it probably means | Correction |
|---|
| ”I’ll add a context provider.” | It is making React coordinate product state. | Ask whether this is Bitfield state or private UI state. |
| ”I’ll import the service.” | It is importing private package code. | Use a named action request. |
| ”I’ll read the package JSON.” | It is bypassing Runtime Kit. | Use a data name. |
| ”I’ll add a global store.” | It is rebuilding traditional shared state. | Classify each value first. |
| ”I’ll pass this through props.” | It may be making the shell coordinate shared product state. | Use Bitfield state when multiple packages need it. |
Required self-report
At the end of generated work, the agent should report this exact shape:Shared product facts:
- selected-file
Data names:
- project-preview-surface
- getting-started-help
Action requests:
- project-preview.refresh-status
- selected-agent.update
Private UI state:
- dropdownOpen
- hoveredRow
Private files/code not used:
- no package store imports
- no package file parsing
- no direct implementation call
- React used only as adapter
Next
