Building a System for AI-Assisted Engineering

I found myself 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 this constant repetition was a major drag on productivity. I realized the problem wasn't the AI's capability—it was its lack of context.

This led me to develop a system to move away from conversational "vibe coding" and toward a more structured, repeatable process for AI-assisted engineering. The goal was to create a single source of truth that could onboard the AI to any project instantly.

This isn't to say conversational "vibe coding" is useless. It's incredibly effective for brainstorming, exploring new ideas, or writing one-off scripts where the long-term cost of inconsistency is zero. But for building complex, long-lived systems, I needed a more rigorous approach. AI-Assisted Engineering provides the structure and predictability required to ensure the codebase remains coherent and maintainable over time.

The Solution: The .ai Directory

The core of my system is a simple .ai/ directory at the project's root. This folder acts as the project's external brain, holding 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, providing guardrails that prevent the AI from inventing incompatible data structures or deviating from established design patterns. SCHEMA.md defines the API contracts, while DESIGN_SYSTEM.md ensures visual consistency.

The Project Constitution

To tie it all together, every project has a CLAUDE.md file at the root. This is the project constitution—a set of rules and conventions the AI must follow. It defines the tech stack, coding standards, and general behavior, ensuring every action the AI takes is aligned with the project's requirements.

Structuring Work with Skills and Commands

With the context in place, the next step was to define the workflow. I broke the system down into a few key concepts:

• Skills: Reusable modules that encode expertise, like how to approach UI design or structure a REST API.
• Rules: The project constitution (CLAUDE.md) that defines constraints and conventions.
• Commands: Executable workflows that combine skills and rules to perform specific actions.

I developed a set of commands to manage the entire development lifecycle:

Planning vs. Execution

I separated the commands into two distinct types.

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

┌─────────────┐     ┌─────────────┐     ┌─────────────┐
│   Client    │────▶│   API       │────▶│  Database   │
│   (React)   │     │   (Node)    │     │  (Postgres) │
└─────────────┘     └─────────────┘     └─────────────┘

Execution commands (/x-plan, /x-build, /x-verify, /x-docs) are deterministic. They take the context and planning outputs and perform concrete actions: write code, run tests, and update documentation. This structured plan -> build -> verify -> docs cycle ensures no steps are skipped.

Why This System Works

This system directly addresses the AI's primary limitation: its context window is its only working memory. By externalizing the project knowledge into files, I give the AI:

• 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 best part is that the system is iterative. If I find a gap in a workflow, I can update the corresponding skill or command. It evolves with my needs.

Getting Started

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

To use it, copy the .claude/ directory into your project. For new projects, you can run /x-feature and /x-ask-architect to generate the initial .ai/ context files. For existing projects, /x-discover will analyze the codebase and build them for you.

While I built this with Claude Code, the principles are universal. A structured .ai/ directory provides valuable context to any AI assistant that can read files, making it a powerful tool for any developer's workflow.