What We Learned Building EvolC

Building EvolC has been a fascinating journey. We're building an AI agent platform using AI agents - the ultimate dogfooding experiment.

Here are the key lessons we've learned.

1. The Filesystem Is Powerful

Initial approach: "We'll need PostgreSQL for organizations, Redis for caching, S3 for file storage, and..."

What we learned: The filesystem is underrated.

We store everything as files:

• config.json for organization settings
• universe.json for business structure
• worlds.json for agent placements
• AGENTS.md for agent context
• .claude/agents/ for agent definitions

Benefits:

• Simple: No database setup, migrations, or connection pooling
• Portable: Copy directory = copy business
• Version control: Git tracks every change
• Human-readable: Open any file and understand it
• Debuggable: No SQL queries, just read files

Trade-offs:

• Doesn't scale to millions of operations/sec (we don't need that)
• No complex queries (our data is simple)
• Requires good file locking (manageable)

Verdict: For most applications, the filesystem is enough. Use a database when you need it, not because it's "best practice."

2. Standards Beat Proprietary Formats

Initial approach: We created CLAUDE.md files for Claude Code agents.

What we learned: There's already a standard - agents.md.

The agents.md format works with:

• Claude Code
• Gemini CLI
• Cursor
• GitHub Copilot
• Aider
• 15+ other AI coding tools

Why this matters:

• Users aren't locked into our platform
• Agents can be used outside EvolC
• We contribute to ecosystem, not fragment it
• More tools = more value for users

Verdict: Always check if a standard exists before creating your own format.

3. Component Duplication Is Insidious

What happened: We created:

• /universe page with force graph
• /world page with agent grid
• /blueprint page with node editor

They all had overlapping functionality. Copy-paste led to bugs.

What we learned:

1. Separate concerns: UI components (components/) vs business logic (lib/)
2. Create primitives: Button, Card, Modal, etc. once
3. Compose, don't duplicate: Build pages from components
4. Refactor early: Don't wait until it's a mess

Solution: Created component-manager agent to handle refactoring on demand.

Verdict: Duplication is easy initially, painful long-term. Refactor proactively.

4. Visual + Code Is the Sweet Spot

Question: Should EvolC be:

• Pure visual (no-code)?
• Pure code (programmers only)?

Answer: Both.

Users need:

• Visual interface to understand structure (force graph, agent grid)
• Code access to customize behavior (AGENTS.md files)

Force graph = macro management (high-level strategy)

Agent grid = micro management (execution details)

Like Factorio or grand strategy games:

• Zoom out: See entire factory/empire
• Zoom in: Optimize individual machines/cities

Verdict: Give users both views. Let them choose their level of abstraction.

5. AI Agents Need Context

Initial approach: "Just tell the AI agent what to do."

What we learned: AI agents perform 10x better with rich context.

Context includes:

• Purpose: What is this department/function for?
• Responsibilities: What should this agent do?
• Constraints: What should it NOT do?
• Examples: Show, don't just tell
• Related files: Where to find information

We provide context through:

• AGENTS.md in each business function directory
• Agent definitions in .claude/agents/
• Business structure in universe.json

Verdict: Context is everything. Invest time in good AGENTS.md files.

6. Dogfooding Reveals Truth

Claim: "EvolC helps you build businesses with AI agents."

Test: Can we build EvolC using EvolC?

Result: Yes, but we found gaps:

• Component refactoring workflow unclear
• Git instructions for agents needed
• Agent coordination still manual

By using our own tool, we found problems before users did.

Verdict: If you don't use your own product, you don't understand your users.

7. Monorepos Are Worth the Setup

Structure:

/evolc├── packages/│   ├── web/      # Next.js frontend│   └── api/      # Hono backend├── docs/          # Documentation├── business/      # Business structure (dogfooding)└── memory/        # Session notes

Benefits:

• Single checkout: Everything in one repo
• Atomic commits: Change frontend + backend together
• Shared types: TypeScript types work across packages
• Easy refactoring: Move code between packages easily

Tools that made it easy:

• Bun workspaces: Dependency management
• Turbopack: Fast builds
• TypeScript path aliases: Clean imports

Verdict: Monorepos have overhead, but the benefits outweigh the costs for multi-package projects.

8. Memory Beats Meetings

Traditional approach:

• Have meeting
• Discuss ideas
• Forget details
• Have same meeting again next week

Our approach:

• Work session with AI agent
• Document everything in /memory directory
• Next session reads previous memory
• Never repeat discussions

The /memory directory is our persistent brain:

• Session notes
• Decisions made
• Ideas explored
• Lessons learned

Verdict: Documentation is asynchronous communication with your future self.

9. Design Systems Prevent Chaos

We defined design tokens upfront:

--bg: #fdfbf7      /* Warm cream */--primary: #e67e22 /* Burnt orange */--border: #e5e7eb  /* Light gray */

Every component uses these tokens. Result:

• Consistent look and feel
• Easy to change theme globally
• Faster development (no "what color?" questions)

Verdict: Spend 1 hour on design system, save 100 hours on component styling.

10. Perfect Is the Enemy of Shipped

We could have:

• Waited for database setup
• Built complex authentication
• Created 20 pages for every feature
• Spent months planning

Instead we:

• Shipped filesystem storage (works great)
• Deferred auth to later (local dev first)
• Built one page with multiple views
• Iterated based on usage

Result: Working product in days, not months.

Verdict: Ship fast, learn from reality, iterate based on feedback.

What's Next

These lessons inform our roadmap:

1. ✅ Filesystem storage (done)
2. ✅ AGENTS.md standard (done)
3. 🚧 Real agent execution (in progress)
4. 🚧 Component refactoring (in progress)
5. 📝 SSE streaming for live updates
6. 📝 Multi-agent coordination
7. 📝 Authentication and authorization
8. 📝 Cloud storage (S3/Tigris)

We're building in public. Follow along at github.com/EvolC-com/evolc.

What lessons have surprised you most? Join the discussion →