Add project bible rules and update README
- rules/patterns/go-project-bible/contract.md: required files, ADL format, runtime-flows rules, what not to duplicate, how to keep current - README.md: rewritten to reflect actual repo purpose and structure Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
This commit is contained in:
65
README.md
65
README.md
@@ -1,41 +1,44 @@
|
||||
# UI Design Code
|
||||
# Bible
|
||||
|
||||
Submodule-first design-code kit for Go web applications and AI coding agents.
|
||||
Shared engineering rules library for Go web projects.
|
||||
|
||||
This repository is meant to be added to host projects as a git submodule and used to
|
||||
copy/sync canonical documentation, AI instruction templates, scaffolds, and UI pattern
|
||||
building blocks.
|
||||
Add as a git submodule to any project — agents (Claude, Codex) will read the rules automatically.
|
||||
|
||||
## Intended Usage
|
||||
|
||||
1. Add as submodule (recommended path: `tools/ui-design-code`)
|
||||
2. Use `tools/designsync` to list/plan/apply bundles into the host repo
|
||||
3. Review changes and commit in the host repo
|
||||
|
||||
## Public Surface (stable)
|
||||
|
||||
- `kit/`
|
||||
- `exports/`
|
||||
- `tools/designsync/`
|
||||
- `README.md`
|
||||
- `VERSIONING.md`
|
||||
- `CHANGELOG.md`
|
||||
|
||||
`demo/` is a runnable reference app and may change faster.
|
||||
|
||||
## Quick Start (this repo)
|
||||
## Usage
|
||||
|
||||
```bash
|
||||
go test ./...
|
||||
go build ./tools/designsync
|
||||
# Add to a project
|
||||
git submodule add https://git.mchus.pro/mchus/bible.git bible
|
||||
|
||||
cd demo
|
||||
go test ./...
|
||||
go run ./cmd/demo-server
|
||||
# Update to latest rules
|
||||
git submodule update --remote bible
|
||||
```
|
||||
|
||||
## Documentation
|
||||
## Structure
|
||||
|
||||
- Architecture source of truth: `bible/README.md`
|
||||
- AI instructions: `CLAUDE.md`, `AGENTS.md`
|
||||
```
|
||||
rules/patterns/ — shared engineering rule contracts
|
||||
go-logging/ — slog, server-side only
|
||||
go-database/ — cursor safety, soft delete, GORM, N+1
|
||||
go-api/ — REST conventions, error format, status codes
|
||||
go-background-tasks/ — Task Manager pattern, polling
|
||||
go-code-style/ — layering, error wrapping, startup sequence
|
||||
go-project-bible/ — how to write and maintain a project bible
|
||||
import-export/ — CSV Excel-compatible format, streaming export
|
||||
table-management/ — toolbar, filtering, pagination
|
||||
modal-workflows/ — state machine, htmx pattern, confirmation
|
||||
forms-validation/ — validation, multi-step flows
|
||||
controls-selection/ — buttons, checkboxes, segmented filters
|
||||
rules/ai/claude/
|
||||
CLAUDE.template.md — base CLAUDE.md template for new projects
|
||||
```
|
||||
|
||||
## Project Setup
|
||||
|
||||
Each project needs:
|
||||
- `bible/` — this submodule
|
||||
- `bible-local/` — project-specific architecture (data model, API, ADL)
|
||||
- `CLAUDE.md` + `AGENTS.md` — point agents to both
|
||||
|
||||
See `rules/ai/claude/CLAUDE.template.md` for a ready-made template.
|
||||
See `rules/patterns/go-project-bible/contract.md` for what goes in `bible-local/`.
|
||||
|
||||
110
rules/patterns/go-project-bible/contract.md
Normal file
110
rules/patterns/go-project-bible/contract.md
Normal file
@@ -0,0 +1,110 @@
|
||||
# Contract: Project Bible (bible-local/)
|
||||
|
||||
## Purpose
|
||||
|
||||
`bible-local/` is the single source of truth for everything **specific to this project**:
|
||||
data model, API surface, business rules, architectural decisions.
|
||||
|
||||
Shared engineering rules (CSV, logging, DB, tables, etc.) live in the `bible/` submodule.
|
||||
Do not duplicate them in `bible-local/`.
|
||||
|
||||
## Required Files
|
||||
|
||||
Every project bible must have these files:
|
||||
|
||||
```
|
||||
bible-local/
|
||||
README.md — index: what files exist and what each covers
|
||||
architecture/
|
||||
system-overview.md — what the product does, active scope, non-goals
|
||||
data-model.md — domain entities, DB tables, naming conventions
|
||||
api-surface.md — all HTTP endpoints with methods and response shape
|
||||
runtime-flows.md — key mutation flows, invariants, critical rules
|
||||
decisions/
|
||||
README.md — ADL format explanation
|
||||
YYYY-MM-DD-topic.md — one file per architectural decision
|
||||
```
|
||||
|
||||
Optional (add when relevant):
|
||||
```
|
||||
architecture/
|
||||
ui-information-architecture.md — page structure, navigation, UI invariants
|
||||
docs/
|
||||
INTEGRATION_GUIDE.md — external system integration (formats, protocols)
|
||||
```
|
||||
|
||||
## system-overview.md Rules
|
||||
|
||||
- List what is **in scope** and what is **explicitly out of scope**.
|
||||
- Out of scope section prevents scope creep — update it when you reject a feature.
|
||||
- Include tech stack and local run command.
|
||||
|
||||
## data-model.md Rules
|
||||
|
||||
- Document canonical naming: if domain model uses `Machine` but API uses `asset`, say so explicitly.
|
||||
- List all DB tables with one-line description of each.
|
||||
- Document any non-obvious invariants (e.g. "parts are projections of history, not source of truth").
|
||||
- Migration policy: how migrations are numbered and applied.
|
||||
|
||||
## api-surface.md Rules
|
||||
|
||||
- Every endpoint: method, path, brief description, key response fields.
|
||||
- Group by domain area (Registry, Ingest, Timeline, etc.).
|
||||
- Note any endpoints that are UI-only routes vs JSON API.
|
||||
- Document pagination, filtering params where non-obvious.
|
||||
|
||||
## runtime-flows.md Rules
|
||||
|
||||
This is the most important file. Document flows that are **easy to break**:
|
||||
|
||||
- Mutation paths (what happens step by step when user does X)
|
||||
- Event/time source priority rules
|
||||
- Deduplication logic
|
||||
- Cross-entity side effects (e.g. removing a component affects asset status)
|
||||
- Anything that caused a bug or regression — add a "DO NOT reintroduce" note
|
||||
|
||||
Format each flow as a numbered list of steps, not prose.
|
||||
|
||||
## Architectural Decision Log (ADL)
|
||||
|
||||
Write a decision entry when:
|
||||
- You choose between two non-obvious approaches
|
||||
- You intentionally reject a feature or pattern
|
||||
- A bug caused a rule change (e.g. cursor safety)
|
||||
- You freeze or deprecate something
|
||||
|
||||
**Format:**
|
||||
|
||||
```markdown
|
||||
# Decision: <short title>
|
||||
|
||||
**Date:** YYYY-MM-DD
|
||||
**Status:** active | superseded by YYYY-MM-DD-topic.md
|
||||
|
||||
## Context
|
||||
What situation made this decision necessary.
|
||||
|
||||
## Decision
|
||||
What was decided, stated clearly.
|
||||
|
||||
## Consequences
|
||||
What this means going forward. What is now forbidden or required.
|
||||
```
|
||||
|
||||
- One decision per file, named `YYYY-MM-DD-short-topic.md`.
|
||||
- When a decision is superseded, add `superseded by` to the old file's status — do not delete it.
|
||||
- Record the decision **in the same commit** as the code that implements it.
|
||||
|
||||
## What NOT to Put in bible-local/
|
||||
|
||||
- Generic rules (CSV format, logging, pagination) → these are in `bible/rules/patterns/`
|
||||
- Work-in-progress notes, TODO lists → use issues or a separate `docs/` folder
|
||||
- Duplicate of what is already in code (don't restate what the code clearly shows)
|
||||
- Speculative future architecture — document what exists, not what might exist
|
||||
|
||||
## Keeping the Bible Current
|
||||
|
||||
- Update `bible-local/` in the **same commit** as the code change it describes.
|
||||
- If you change a flow, update `runtime-flows.md` in the same PR.
|
||||
- If a section becomes outdated, fix or delete it — stale docs are worse than no docs.
|
||||
- Bible files are in **English only**.
|
||||
Reference in New Issue
Block a user