Building a System for AI-Assisted Engineering

I kept starting every session with my AI assistant the same way — explaining the project’s tech stack, API design, and coding conventions from scratch. The AI had no memory of our last conversation, and the constant repetition was a drag on productivity. The problem wasn’t the AI’s capability. It was the lack of context.

This pushed me to move away from conversational “vibe coding” and toward a structured, repeatable process for AI-assisted engineering. The goal: a single source of truth that could onboard the AI to any project instantly.

To be clear, conversational vibe coding is not useless. It is effective for brainstorming, exploring ideas, or writing one-off scripts where the long-term cost of inconsistency is zero. But for complex, long-lived systems, I needed something more rigorous — a system that keeps the codebase coherent and maintainable over time.

The .ai/ directory

The core of the system is a .ai/ directory at the project root. It acts as the project’s external brain — a set of markdown files that define its DNA:

.ai/
├── PRD.md           # Product requirements and personas
├── SCHEMA.md        # Data structures and API contracts
├── DESIGN_SYSTEM.md # UI tokens and component patterns
├── VIEWS.md         # UI layouts and route structure
├── ROADMAP.md       # Prioritized task backlog
└── DECISIONS.md     # Architecture Decision Records (ADRs)

Each file serves a specific purpose. SCHEMA.md defines API contracts so the AI does not invent incompatible data structures. DESIGN_SYSTEM.md enforces visual consistency. DECISIONS.md records the “why” behind architectural choices, preventing the AI from relitigating settled debates.

The project constitution

To tie it together, every project gets a CLAUDE.md at the root. This is the project constitution — tech stack, coding standards, behavioral rules. Everything the AI needs to know before writing a single line of code. It ensures every action is aligned with the project’s requirements.

Structuring work with skills and commands

With context in place, the next step was defining the workflow. I broke it into three concepts:

• Skills — reusable modules encoding expertise (how to approach UI design, structure a REST API)
• Rules — the project constitution (CLAUDE.md) defining constraints and conventions
• Commands — executable workflows combining skills and rules for specific actions

The commands cover the full development lifecycle:

Command	Purpose
/x-feature	Plan new features from a product perspective
/x-ask-architect	Discuss architecture with diagrams and trade-offs
/x-ask-ui-ux-designer	Make UI/UX decisions with mockups and user flows
/x-plan	Read project context and identify the next task
/x-build	Implement code according to established patterns
/x-verify	Run linters, builds, and tests to validate work
/x-docs	Update the roadmap and record architectural decisions
/x-discover	Reverse-engineer an existing codebase into .ai/ structure

Planning vs. execution

I separated commands into two distinct types.

Planning commands (/x-feature, /x-ask-architect) are conversational. They help think through problems by simulating discussions with domain experts, complete with diagrams and trade-off analysis.

Execution commands (/x-plan, /x-build, /x-verify, /x-docs) are deterministic. They take the context and planning outputs, then perform concrete actions: write code, run tests, update documentation.

This structured cycle ensures no steps get skipped. Plan, build, verify, document — then iterate.

Why this works

The system addresses the AI’s primary limitation: its context window is its only working memory. By externalizing project knowledge into files, the AI gets:

• Persistent memory — context survives across sessions
• Shared understanding — the .ai/ directory is the single source of truth
• Consistency and guardrails — schemas and design systems prevent architectural drift

The system is also iterative. When I find a gap in a workflow, I update the corresponding skill or command. It evolves with the project.

Getting started

The system is available on GitHub: xcke/x-ai-system.

Copy the .claude/ directory into your project. For new projects, run /x-feature and /x-ask-architect to generate the initial .ai/ context files. For existing projects, /x-discover analyzes the codebase and builds them for you.

While I built this with Claude Code, the principles are universal. A structured .ai/ directory provides context to any AI assistant that can read files.