flowmade-one/architecture
3
0
Fork 0
Code Issues 15 Pull Requests 1 Actions Packages Projects Releases Wiki Activity

Add CLAUDE.md guidance and repository map

Browse Source 
- Create claude-md-writing skill with best practices for CLAUDE.md files
- Create repos.md registry of all repos with status (Active/Planned/Splitting)
- Update /create-repo to include organization context section
- Update repo-conventions to reference new skill

Each repo's CLAUDE.md now links to manifesto, repos.md, and vision.md
so Claude always understands the bigger picture.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
Hugo Nijhuis
2026-01-08 10:24:10 +01:00
parent 0e1a65f0e3
commit 057d4dac57
4 changed files with 309 additions and 2 deletions
Download Patch File Download Diff File Expand all files Collapse all files

14
commands/create-repo.md
View File

@@ -7,6 +7,7 @@ argument-hint: <repo-name>
@~/.claude/skills/repo-conventions/SKILL.md
@~/.claude/skills/vision-management/SKILL.md
@~/.claude/skills/claude-md-writing/SKILL.md
@~/.claude/skills/gitea/SKILL.md
Create a new repository with Flowmade's standard structure.
@@ -44,12 +45,19 @@ Create a new repository with Flowmade's standard structure.
- Link to `../architecture/manifesto.md`
- Fill in based on user's answers
7. **Create CLAUDE.md**:
7. **Create CLAUDE.md** (following claude-md-writing skill):
```markdown
# <Repo Name>
<One-line description from step 3>
## Organization Context
This repo is part of Flowmade. See:
- [Organization manifesto](../architecture/manifesto.md) - who we are, what we believe
- [Repository map](../architecture/repos.md) - how this fits in the bigger picture
- [Vision](./vision.md) - what this specific product does
## Setup
```bash
@@ -67,6 +75,10 @@ Create a new repository with Flowmade's standard structure.
make test # Run tests
make lint # Run linters
```
## Architecture
TODO: Document key patterns and conventions once established.
```
8. **Create Makefile** (basic template):

71
repos.md Normal file
View File

@@ -0,0 +1,71 @@
# Repository Map
Central registry of all Flowmade repositories.
## How to Use This
Each repo's CLAUDE.md should reference this map for organization context. When working in any repo, Claude can check here to understand how it fits in the bigger picture.
**Status markers:**
- **Active** - Currently in use
- **Splitting** - Being broken into smaller repos
- **Planned** - Will be created (from split or new)
## Repositories
### Organization
| Repo | Purpose | Status | Visibility |
|------|---------|--------|------------|
| architecture | Org source of truth: manifesto, Claude tooling, learnings | Active | Public |
### Platform
| Repo | Purpose | Status | Visibility |
|------|---------|--------|------------|
| arcadia | Monorepo containing platform code | Splitting | Private |
| aether | Event sourcing runtime with bytecode VM | Planned (from Arcadia) | Private |
| iris | WASM UI framework | Planned (from Arcadia) | Public |
| eskit | ES primitives (aggregates, events, projections, NATS) | Planned (from Arcadia) | Public |
| adl | Domain language compiler | Planned (from Arcadia) | Private |
| studio | Visual process designer, EventStorming tools | Planned (from Arcadia) | Private |
### Infrastructure
| Repo | Purpose | Status | Visibility |
|------|---------|--------|------------|
| gitserver | K8s-native git server (proves ES/IRIS stack) | Planned | Public |
## Relationships
```
arcadia (splitting into):
├── eskit (standalone, foundational)
├── iris (standalone)
├── aether (imports eskit)
├── adl (imports aether)
└── studio (imports aether, iris, adl)
gitserver (will use):
├── eskit (event sourcing)
└── iris (UI)
```
## Open Source Strategy
See [repo-conventions skill](skills/repo-conventions/SKILL.md) for classification criteria.
**Open source** (public):
- Generic libraries that benefit from community (eskit, iris)
- Infrastructure tooling that builds awareness (gitserver)
- Organization practices and tooling (architecture)
**Proprietary** (private):
- Core platform IP (aether VM, adl compiler)
- Product features (studio)
## Related
- [Manifesto](manifesto.md) - Organization identity and beliefs
- [Issue #53](https://git.flowmade.one/flowmade-one/architecture/issues/53) - Git server proposal
- [Issue #54](https://git.flowmade.one/flowmade-one/architecture/issues/54) - Arcadia split planning

217
skills/claude-md-writing/SKILL.md Normal file
View File

@@ -0,0 +1,217 @@
---
name: claude-md-writing
description: Write effective CLAUDE.md files that give AI assistants the context they need. Use when creating new repos, improving existing CLAUDE.md files, or setting up projects.
---
# Writing Effective CLAUDE.md Files
CLAUDE.md is the project's context file for AI assistants. A good CLAUDE.md means Claude understands your project immediately without needing to explore.
## Purpose
CLAUDE.md answers: "What does Claude need to know to work effectively in this repo?"
- **Not a README** - README is for humans discovering the project
- **Not documentation** - Docs explain how to use the product
- **Context for AI** - What Claude needs to make good decisions
## Required Sections
### 1. One-Line Description
Start with what this repo is in one sentence.
```markdown
# Project Name
Brief description of what this project does.
```
### 2. Organization Context
Link to the bigger picture so Claude understands where this fits.
```markdown
## Organization Context
This repo is part of Flowmade. See:
- [Organization manifesto](../architecture/manifesto.md) - who we are, what we believe
- [Repository map](../architecture/repos.md) - how this fits in the bigger picture
- [Vision](./vision.md) - what this specific product does
```
### 3. Setup
How to get the project running locally.
```markdown
## Setup
\`\`\`bash
# Clone and install
git clone <url>
cd <project>
make install # or npm install, etc.
\`\`\`
```
### 4. Project Structure
Key directories and what they contain. Focus on what's non-obvious.
```markdown
## Project Structure
\`\`\`
project/
├── cmd/ # Entry points
├── pkg/ # Shared packages
│ ├── domain/ # Business logic
│ └── infra/ # Infrastructure adapters
├── internal/ # Private packages
└── api/ # API definitions
\`\`\`
```
### 5. Development Commands
The commands Claude will need to build, test, and run.
```markdown
## Development
\`\`\`bash
make build # Build the project
make test # Run tests
make lint # Run linters
make run # Run locally
\`\`\`
```
### 6. Architecture Decisions
Key patterns and conventions specific to this repo.
```markdown
## Architecture
### Patterns Used
- Event sourcing for state management
- CQRS for read/write separation
- Hexagonal architecture
### Conventions
- All commands go through the command bus
- Events are immutable value objects
- Projections rebuild from events
```
## What Makes a Good CLAUDE.md
### Do Include
- **Enough context to skip exploration** - Claude shouldn't need to grep around
- **Key architectural patterns** - How the code is organized and why
- **Non-obvious conventions** - Things that aren't standard
- **Important dependencies** - External services, APIs, databases
- **Common tasks** - How to do things Claude will be asked to do
### Don't Include
- **Duplicated manifesto content** - Link to it instead
- **Duplicated vision content** - Link to vision.md
- **API documentation** - That belongs elsewhere
- **User guides** - CLAUDE.md is for the AI, not end users
- **Obvious things** - Don't explain what `go build` does
## Template
```markdown
# [Project Name]
[One-line description]
## Organization Context
This repo is part of Flowmade. See:
- [Organization manifesto](../architecture/manifesto.md) - who we are, what we believe
- [Repository map](../architecture/repos.md) - how this fits in the bigger picture
- [Vision](./vision.md) - what this specific product does
## Setup
\`\`\`bash
# TODO: Add setup instructions
\`\`\`
## Project Structure
\`\`\`
project/
├── ...
\`\`\`
## Development
\`\`\`bash
make build # Build the project
make test # Run tests
make lint # Run linters
\`\`\`
## Architecture
### Patterns
- [List key patterns]
### Conventions
- [List important conventions]
### Key Components
- [Describe main components and their responsibilities]
```
## Examples
### Good: Enough Context
```markdown
## Architecture
This service uses event sourcing. State is rebuilt from events, not stored directly.
### Key Types
- `Aggregate` - Domain object that emits events
- `Event` - Immutable fact that something happened
- `Projection` - Read model built from events
### Adding a New Aggregate
1. Create type in `pkg/domain/`
2. Implement `HandleCommand()` and `ApplyEvent()`
3. Register in `cmd/main.go`
```
Claude can now work with aggregates without exploring the codebase.
### Bad: Too Vague
```markdown
## Architecture
Uses standard Go patterns. See the code for details.
```
Claude has to explore to understand anything.
## Maintenance
Update CLAUDE.md when:
- Adding new architectural patterns
- Changing project structure
- Adding important dependencies
- Discovering conventions that aren't documented
Don't update for:
- Every code change
- Bug fixes
- Minor refactors

9
skills/repo-conventions/SKILL.md
View File

@@ -75,13 +75,20 @@ This product vision builds on the [organization manifesto](../architecture/manif
### CLAUDE.md
Project-specific instructions for Claude Code.
Project-specific context for AI assistants. See [claude-md-writing skill](../claude-md-writing/SKILL.md) for detailed guidance.
```markdown
# [Project Name]
[One-line description]
## Organization Context
This repo is part of Flowmade. See:
- [Organization manifesto](../architecture/manifesto.md) - who we are, what we believe
- [Repository map](../architecture/repos.md) - how this fits in the bigger picture
- [Vision](./vision.md) - what this specific product does
## Setup
[How to get the project running locally]