init - build foundation #1
nico
Loading…
Add table
Add a link
Reference in a new issue
No description provided.
Delete branch "%!s()"
Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?
Project Bootstrap Prompt
Create a production-ready Go web application that follows the architectural philosophy of Miniflux v2.
Core Philosophy
Web Stack
Backend:
Frontend:
Authentication
Implement session-based authentication.
Features:
User roles:
Permissions:
Anonymous
User
Admin
Do not hardcode permissions.
Design a reusable authorization layer.
API
Expose a versioned REST API.
Base path:
/api/v1
Authentication:
Return JSON.
Create endpoints:
GET /health
GET /me
POST /login
POST /logout
GET /users
(admin)
GET /users/{id}
(admin)
POST /users
(admin)
PUT /users/{id}
(admin)
DELETE /users/{id}
(admin)
Separate API handlers from HTML handlers.
Business logic should be shared.
Pages
Initially only create:
/
A welcome page.
Content:
Authenticated users visiting "/" should be redirected to "/dashboard".
Dashboard can initially display:
Welcome, {{username}}
Templates
Use html/template.
Structure:
templates/
layout.html
header.html
footer.html
welcome.html
login.html
dashboard.html
admin/
users.html
Use template inheritance or composition.
Static Assets
/assets
/css
/app.css
/js
/app.js
/images
Embed all assets into the Go binary.
Database
Use PostgreSQL.
Use plain SQL.
No ORM.
Provide SQL migrations.
Suggested tables:
users
sessions
schema_migrations
Users:
id
email
username
password_hash
role
created_at
updated_at
Sessions:
id
user_id
token
expires_at
created_at
Project Structure
cmd/
server/
internal/
auth/
config/
database/
handlers/
middleware/
models/
services/
storage/
templates/
api/
ui/
assets/
migrations/
Keep packages small and cohesive.
Architecture Rules
HTTP handlers should never contain business logic.
Business logic belongs in services.
Database access belongs in repositories/storage.
Templates should only render data.
Middleware handles:
Configuration
Support:
environment variables
.env file
development
production
Logging
Structured logging.
Request logging.
Error logging.
No println debugging.
Error Handling
Central error renderer.
HTML requests return HTML errors.
API requests return JSON errors.
Security
CSRF protection.
Content Security Policy.
Secure cookies.
Password hashing.
Input validation.
Parameterized SQL.
Rate limiting hooks.
Testing
Include:
unit tests for services
repository tests
handler tests
Future Extensibility
The architecture should make it easy to later add:
without requiring a rewrite.
Code Style
Prefer explicit code over abstraction.
Avoid unnecessary interfaces.
Avoid dependency injection frameworks.
Keep functions small.
Write readable SQL.
Favor composition over inheritance.
Generate complete working code with explanatory comments where appropriate.
very fist / setup:
Bootstrap an AI-First Go Project
Initialize this repository for long-term AI-assisted development.
The goal is to create a codebase that remains simple, maintainable, and enjoyable to work on for years—not just one that works today.
The project philosophy is heavily inspired by:
The repository should optimize for clarity over cleverness.
Generate the following files
AGENT.md
Create a comprehensive guide describing how AI agents should work inside this repository.
Include the following sections.
Mission
Build software that is:
Optimize for the next developer reading the code.
Engineering Values
Always prefer:
Never optimize for novelty.
Core Principles
Follow these principles in order.
Performance only matters after measurement.
YAGNI
Do not implement future features.
Do not create extension points without actual consumers.
Do not build configuration systems before they are needed.
Ponytail Rule
Every abstraction must have at least two real use cases.
Never introduce:
unless there are at least two concrete implementations or consumers.
Duplication is acceptable until patterns emerge.
KISS
Prefer:
small packages
small files
small functions
small structs
small commits
TDD
Every feature should follow:
Red
Green
Refactor
Write the failing test first.
Implement only enough code to pass.
Refactor only after all tests pass.
Tests should explain behavior.
Architecture
Use a modular monolith.
One binary.
One PostgreSQL database.
One deployable artifact.
One codebase.
Tech Stack
Language
Backend
Frontend
Database
Assets
No:
Layering
Handlers
↓
Application Services
↓
Storage
↓
PostgreSQL
Business logic must never exist in handlers.
Templates should never contain business logic.
Dependency Policy
Before adding a dependency ask:
Can the Go standard library solve this?
Can existing code solve this?
Does this dependency remove more code than it adds?
If not, don't add it.
Coding Style
Prefer:
early returns
descriptive names
small functions
explicit errors
clear SQL
simple templates
Avoid:
magic
reflection
hidden state
global mutable variables
over-abstraction
premature optimization
Error Handling
Return errors.
Wrap errors with context.
Never panic in business logic.
Render friendly HTML errors.
Return structured JSON API errors.
Logging
Use structured logging.
No debug print statements.
Log meaningful events only.
Security
Always:
validate input
hash passwords
parameterize SQL
protect against CSRF
use secure cookies
use Content Security Policy
Definition of Done
A task is complete only when:
AI Workflow
Before writing code:
Understand existing code.
Search before creating.
Reuse before rewriting.
Prefer editing existing files over creating new ones.
Never rename large parts of the project unless explicitly requested.
Avoid large rewrites.
Explain trade-offs.
Keep commits focused.
README.md
Create a concise README containing:
Purpose
Technology
Architecture
Getting Started
Development
Testing
Project Structure
Philosophy
SPEC.md
Describe the application.
Include:
Purpose
Target users
Core features
Authentication
Authorization
REST API
Pages
Future roadmap
Explicit non-goals
Keep this document short and easy to update.
TASKS.md
Maintain a living backlog.
Sections:
Now
Next
Later
Ideas
Done
Tasks should be small enough to finish within one focused session.
CONTRIBUTING.md
Document:
Development setup
Running locally
Database migrations
Testing
Linting
Formatting
Commit message conventions
Pull request expectations
Definition of Done
DECISIONS.md
Maintain a chronological engineering decision log.
Each entry should include:
Date
Decision
Reasoning
Alternatives considered
Consequences
Use this for lightweight architectural history.
docs/architecture.md
Describe:
System overview
HTTP request lifecycle
Package organization
Layer responsibilities
Authentication flow
API design
Template rendering
Database access
Keep diagrams ASCII only.
adr/0001-simple-stack.md
Document why the project intentionally avoids:
Frontend frameworks
ORMs
Microservices
Dependency injection
Enterprise architecture
Discuss the trade-offs honestly.
Makefile
Create developer commands:
fmt
test
lint
check
run
build
clean
.golangci.yml
Configure sensible linting.
Avoid extremely opinionated rules.
Prioritize correctness and readability.
Repository Standards
The repository should encourage:
small commits
small pull requests
frequent testing
explicit code
minimal dependencies
simple architecture
long-lived maintainability
General Rules
Whenever implementing code:
If multiple valid implementations exist, choose the one with the fewest concepts, the fewest moving parts, and the smallest maintenance burden.