Accessibility used to mean one thing: making software usable for people with disabilities. Screen readers, color contrast, keyboard navigation. Important work. Still is.
But something shifted. With Claude Code and the wave of AI coding agents that followed, your codebase now has a second class of "user" that needs to navigate it, understand it, and work within it. The AI is a developer on your team, and your codebase is either accessible to it or it isn't.
This isn't a metaphor. It's an architectural decision with measurable consequences. A codebase that's "AI-accessible" produces better AI output — fewer hallucinations, fewer broken implementations, faster iteration. A codebase that's hostile to AI context windows produces garbage, and you'll spend more time correcting the AI than you would have spent writing the code yourself.
The developer is now an architect
Let's be direct about what happened: Claude Code turned senior developers into architects. The day-to-day of writing implementation code is increasingly delegated to AI. What remains — and what's harder than ever — is the structural work: deciding how the codebase is organized, what patterns to use, how modules communicate, what context the AI needs to make good decisions.
This is a role shift, not a skill downgrade. An architect who structures a codebase well can get 10x output from Claude Code. An architect who doesn't will fight the AI on every task. The multiplier effect of good architecture has always existed. AI makes it exponential.
Rule 1: The monorepo is non-negotiable
If your frontend and backend live in separate repositories, your AI is working with half the context. It can see the API call but not the endpoint. It can see the database schema but not the component that renders the data. Every time the AI needs to cross the repo boundary, it loses context, hallucinates an interface, or asks you for information it should already have.
A monorepo gives the AI the complete picture. The React component, the API route it calls, the database query that powers it, the types that connect them — all visible in one context window. This isn't just convenient. It's the difference between the AI generating a component that works on the first try and one that calls an endpoint with the wrong payload shape.
frontend/ → AI sees this
backend/ → AI doesn't see this
shared/ → AI doesn't see this either
# Result: AI guesses the API contract. Often wrong.
# AI-accessible: monorepo
app/
apps/mobile/ → frontend
apps/api/ → backend
packages/shared/ → shared types, utils
# Result: AI reads the endpoint, understands the types,
# generates a component that works.
We moved to a monorepo six months ago. The immediate effect: Claude Code's first-attempt success rate on cross-stack features went from ~40% to ~85%. Same AI, same prompts, different codebase structure.
Rule 2: Types are documentation for AI
TypeScript isn't just type safety. It's the densest form of documentation your AI will ever read. A well-typed interface tells Claude Code more about your data model than a README ever could. The AI reads the type, infers the shape of the data, understands the constraints, and generates code that respects them.
Untyped JavaScript is the AI equivalent of a dark room. The AI can't see the shape of anything. It guesses. Sometimes it guesses right. Often it doesn't. any is the enemy of AI-assisted development — not because of runtime safety, but because it destroys the context that makes AI output reliable.
async function getUser(id) {
const res = await db.query('SELECT * FROM users');
return res;
}
// AI-accessible: AI knows exactly what it's working with
interface User {
id: string;
email: string;
plan: 'free' | 'pro' | 'enterprise';
createdAt: Date;
trialEndsAt: Date | null;
}
async function getUser(id: string): Promise<User | null> {
return db.user.findUnique({ where: { id } });
}
Rule 3: Name things for readers, not writers
Developers name things for speed. handleClick, processData, utils. These names make sense when you wrote them. They're meaningless to an AI navigating your codebase for the first time — which is every time, because AI has no persistent memory of your project between sessions.
handlePaywallSubscribeButtonClick is ugly. It's also unambiguous. The AI knows exactly what this function does, where it's used, and what kind of changes it should make. handleClick could be anything. The AI has to read the entire function body, trace the call chain, and infer the context. That's wasted context window and increased error probability.
This applies to files too. utils.ts is a junk drawer that tells the AI nothing. pricing-calculations.ts tells it everything. The cost of verbose names is zero. The cost of ambiguous names is measured in AI mistakes.
Rule 4: Co-locate everything
The traditional pattern: all components in /components, all hooks in /hooks, all types in /types, all tests in /__tests__. This makes sense for humans who think in categories. It's terrible for AI that thinks in context.
When Claude Code needs to modify the paywall screen, it needs the component, its hooks, its types, and its tests. If those are scattered across four directories, the AI either loads too much context (burning tokens on unrelated files) or too little (missing the hook that manages state). Co-located feature folders solve this.
src/
components/Paywall.tsx
hooks/usePaywall.ts
types/paywall.ts
tests/Paywall.test.ts
styles/Paywall.css
# AI needs to navigate 5 directories to understand one feature
# AI-accessible: organized by feature
src/features/paywall/
Paywall.tsx
usePaywall.ts
paywall.types.ts
paywall.test.ts
# AI loads one folder. Complete context. Done.
Rule 5: E2E tests in simulators — the AI's QA loop
This is the most forward-looking change we've made: end-to-end tests that the AI can run autonomously in a simulator.
The traditional workflow: the AI writes code, the developer runs it, visually checks if it works, reports back. This is slow and defeats the purpose of AI-assisted development. The AI should be able to verify its own work.
We set up Detox (for React Native) running against an iOS Simulator and Android Emulator in CI. Claude Code can trigger these tests after generating code. The flow becomes: AI writes code → AI runs E2E tests → tests pass → AI moves to next task. Or: tests fail → AI reads the error → AI fixes the code → AI reruns. No human in the loop for verification.
This requires investment upfront. You need a robust E2E test suite before the AI can use it. You need tests that are deterministic, fast, and meaningful. But once it's in place, the AI becomes semi-autonomous: it can implement a feature, verify it works, fix what's broken, and deliver a tested result — without a human checking every step.
Rule 6: CLAUDE.md is your most important file
Claude Code reads a CLAUDE.md file at the root of your repo as system-level context. This is where you encode everything the AI needs to know about your project that isn't expressed in code: architectural decisions, naming conventions, patterns to follow, patterns to avoid, deployment procedures, testing requirements.
## Architecture
Monorepo: apps/mobile (Expo/RN), apps/api (Node/Hono)
Shared types in packages/shared — always import from here
Database: Postgres via Drizzle ORM
## Conventions
- Feature folders in src/features/[name]/
- Every feature has: Component, hook, types, test
- API routes follow REST. No GraphQL.
- State: Zustand for global, React Query for server
## Do NOT
- Use any type. Ever. Define the type.
- Create files called utils, helpers, or misc
- Add dependencies without checking bundle size
- Use default exports (named exports only)
## Testing
- E2E: Detox. Run with: yarn test:e2e
- Unit: Vitest. Run with: yarn test
- Always run tests after changes to verify
Think of it as the onboarding document for a new developer — except this developer has perfect recall, zero ego, and will follow your instructions to the letter. Every minute you spend on CLAUDE.md saves hours of correcting AI output.
The checklist
If you're starting a new project today and plan to use AI coding tools, here's what to set up before writing a single feature:
Monorepo. Front and back in one repo. Shared types package. AI sees everything.
Strict TypeScript. No any. No implicit types. Every function signature is explicit. Types are documentation.
Feature folders. Co-locate component, hook, types, and test. One folder per feature. AI loads one folder, gets full context.
Descriptive naming. Files, functions, variables. Verbose is better than clever. The AI will thank you by generating code that fits.
CLAUDE.md. Your project's architectural brain dump. Conventions, anti-patterns, commands. Updated weekly.
E2E test suite in simulator. Detox or Maestro. AI can run tests autonomously. The feedback loop closes without human intervention.
Linting as guardrails. ESLint, Prettier, strict mode. The AI will generate code that violates your conventions. Automated linting catches it before you see it.
For twenty years, accessibility meant making software usable for humans with different abilities. That was the right thing to do, and it still is. But the word has expanded. Your codebase now has a non-human collaborator that reads your code, infers your patterns, and generates new code based on what it understands. How well it performs depends entirely on how accessible your codebase is to it. The teams that internalize this early will ship faster than the ones who don't. That's not a prediction. We're already seeing it.