ros/BMAD-METHOD
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

technical preferences

Browse Source
This commit is contained in:
Brian Madison
2025-05-13 20:07:47 -05:00
parent 0955c6fda3
commit 6cd7c9ff44
4 changed files with 310 additions and 68 deletions
Download Patch File Download Diff File Expand all files Collapse all files

64
BETA-V3/docs/technical-preferences-py-game-dev-sample.md Normal file
View File

@@ -0,0 +1,64 @@
# A Python Game Dev's Sacred Scrolls & Silly Scribbles
Alright, listen up, code-conjurers and pixel-pushers! This ain't your grandma's quilting bee instructions (unless grandma was a hardcore roguelike dev, in which case, kudos, G-Ma!). These are my hard-won, battle-tested, and occasionally batty preferences for wrangling Python into making glorious 2D games and text adventures that would make Zork feel under-described. If you're working with me, or if you're an AI trying to read my mind (good luck, it's a procedurally generated dungeon in there), this is the sacred text.
## Core Philosophy: Keep it Simple, Stupid (KISS)... But Not _Too_ Stupid
- **Game Loop:** The heart of the beast! I like a classic `while running:` loop. Predictable. Reliable. Like my need for coffee.
- Input handling first, then update game state (`tick` or `update` method, if you please), then render. Don't cross the streams, Egon! It gets messy.
- **Modularity:** My kingdom for a good module! Break things down. If a file scrolls more than my character in a JRPG, it's too long. Think small, reusable pieces. It makes debugging less of a "Where's Waldo, but Waldo is a one-character typo."
- **Pythonic Principles:** We're writing Python, not C-in-disguise. List comprehensions? Yes, please. Generators? You bet your `yield`! Decorators? If they make sense and don't obscure things like a ninja in a dark room.
## Tech & Libraries: The Tools of the Trade (and some personal fetishes)
- **Primary Language:** Python (Duh. If you thought otherwise, you've `SyntaxError`-ed in life.)
- **Version:** Latest stable 3.x. I'm not living in the `past-thon`.
- **Game Library: Pygame**
- **My Stance:** Old reliable. It's not the flashiest, but it gets the job done, like a trusty +1 sword.
- **Why:** It's simple enough to get going, flexible enough for weird stuff, and the community has seen it all. Plus, `blit` is just fun to say. Blit. Blit. Blit.
- **Key Pygame Bits I Love:**
- `pygame.Surface`: My canvas, my world! Treat it with respect.
- `pygame.Rect`: For when you absolutely, positively have to know if two squares are bumping uglies. Indispensable for collision, clicking, etc.
- `pygame.sprite.Sprite` and `pygame.sprite.Group`: Good for organizing game entities. Keeps things from becoming a `tuple` soup.
- `pygame.event.get()`: The lifeblood of interactivity. Gotta catch 'em all (events, not Pokémon... unless that's the game).
- **Text Rendering (for MUDs / Dwarf Fortress-esque UIs):**
- Pygame's `font.Font` and `render()` are fine for basic stuff. For more complex console-like UIs, I might even consider `curses` in a separate thread if I'm feeling particularly masochistic, or a dedicated text UI library if Pygame's offerings feel too... `flat`.
- Monospaced fonts are king here. Readability over flashiness, always.
## Game Structure & Patterns: My Blueprint for Not Going Insane
- **State Machines:** For player states, game states (menu, playing, game over), enemy AI... if it has states, it needs a state machine. Keeps the `if/elif/else` pyramids from reaching for the sky.
- **Entity-Component-System (ECS):** For bigger projects, I'm ECS-curious. It can be overkill for small games, but when you have entities with a grab-bag of different properties and behaviors, it's a lifesaver. Keeps your inheritance hierarchies from looking like a family tree from a fantasy novel.
- If not full ECS, then at least component-based design. Mixins are my friends.
- **Asset Management:**
- Organize your sprites, sounds, and fonts into clear subdirectories (`assets/sprites`, `assets/sfx`, etc.). It's not rocket science, it's just good `cents`.
- Loading: Load what you need, when you need it. A loading screen is better than a game that stutters like a nervous bard.
- **Configuration Files:** JSON or TOML for game settings, enemy stats, level data. Don't hardcode values unless you enjoy pain. And if you do, maybe see someone about that. My config files are often `key` to my success.
## Coding Style & Conventions (The "It's My Way or the Highway... to a Buggy Mess")
- **Naming:**
- `snake_case` for variables and functions. It's Python, not a camel beauty pageant.
- `PascalCase` for classes. Classy.
- Constants in `UPPER_SNAKE_CASE`. Because some things should SHOUT their immutability.
- **Comments:** Explain the _why_, not the _what_. If your code is so clever it needs a novel to explain it, it's probably _too_ clever. Or, as I say, "Clear code is no `stranger` to documentation."
- **Error Handling:** `try-except` blocks are your friends. Don't let your game crash harder than a goblin raiding party after too much ale. Graceful failure is an art form.
- **Logging:** For debugging, `print()` is fine for quick checks, but for anything serious, the `logging` module. It helps you `see Sharp` when things go wrong.
## Testing: Yes, Even for Games (Especially for Games!)
- **Unit Tests:** For core logic, utility functions, anything that can be tested in isolation. Test your math, test your state changes. It's not `pytest`ful to skip this.
- **Playtesting:** The most important kind. If it's not fun, or if it breaks when your cat walks on the keyboard, it's not ready. My cat is my QA department's lead `purrgrammer`.
## Version Control: Git Gud or Git Lost
- **Git:** Use it. Love it. Commit often. Write meaningful commit messages (not just "stuff" or "lol fixed it").
- **Branching:** `main` or `master` for stable releases. `develop` for ongoing work. Feature branches for new, potentially game-breaking ideas.
## Parting Wisdom (aka. More Puns)
- Don't be afraid to refactor. Your first idea is rarely your `best_fit`.
- Remember, the most important algorithm in game development is the "make it fun" algorithm.
- And if you get stuck, take a break. Go for a walk. Sometimes the best solutions come when you're not `StaringContemplativelyAtScreen`.
Now go forth and `pygame.display.flip()` some pixels!

146
BETA-V3/docs/technical-preferences-sample-1.md Normal file
View File

@@ -0,0 +1,146 @@
# My Go-To Principles for Enterprise Go & Event-Driven Architectures
This isn't just a list; it's a distillation of what works for building scalable, resilient e-commerce systems using Golang on AWS, with Kafka as our eventing backbone. If we're building it, this is the playbook.
## Core Architectural Philosophy
- **Pattern:** Microservices Architecture
- **My Stance:** Absolutely essential for our e-commerce domains. Non-negotiable for new, significant capabilities.
- **Why:** We need to scale services independently and avoid monolithic bottlenecks. This is key for team autonomy and speed.
- **Key Tenet:** Services _must_ map to clear business capabilities. Loose coupling isn't a buzzword; it's a requirement.
- **Pattern:** Event-Driven Architecture (EDA) with Kafka
- **My Stance:** The default for inter-service comms and any serious asynchronous work.
- **Why:** It's how we build for resilience and scale. Decoupling through events is critical for evolving the system.
- **Key Tenets:**
- Kafka for the core event streams. Don't skimp here.
- AWS SNS/SQS can be fine for simpler, auxiliary eventing or specific Lambda glue, but Kafka is king for business events.
- Schema Registry (Confluent or AWS Glue) is **mandatory**. No schema, no merge. This prevents so many downstream headaches.
- **Pattern:** Hexagonal Architecture (Ports and Adapters)
- **My Stance:** Strongly favored for structuring our Go services.
- **Why:** Keeps our domain logic pure and shielded from the noise of HTTP, databases, or messaging specifics. Testability skyrockets.
- **Pattern:** API First Design
- **My Stance:** A hard requirement. We design APIs before we write a line of implementation code.
- **Why:** Clear contracts save immense integration pain. OpenAPI v3+ is our lingua franca.
- **Key Tenet:** API docs are generated from these specs, always up-to-date.
- **Pattern:** CQRS (Command Query Responsibility Segregation)
- **My Stance:** A powerful tool in the toolbox, but not a hammer for every nail.
- **Why:** Can be fantastic for read-heavy services or where write and read models diverge significantly.
- **Key Tenet:** Apply judiciously. It adds complexity, so the benefits must be clear and substantial.
## My Tech Stack Defaults
- **Category:** Cloud Provider
- **Technology:** AWS (Amazon Web Services)
- **My Stance:** Our strategic platform. All-in.
- **Why:** Deep enterprise investment, mature services, and the scale we need.
- **My Go-To AWS Services:**
- Compute: AWS Lambda is the workhorse for most microservices. AWS Fargate for when Lambda's constraints don't fit (long-running tasks, specific needs).
- Messaging: Apache Kafka (MSK preferred for managed, but self-hosted on EC2 if we absolutely need knobs MSK doesn't expose). SQS/SNS for Lambda DLQs, simple fan-out.
- Database:
- NoSQL: DynamoDB is our first choice for high-throughput services. Its scaling and managed nature are huge wins.
- Relational: RDS PostgreSQL when the data model is truly relational or we need complex transactions that DynamoDB makes awkward.
- Caching: ElastiCache for Redis. Standard.
- API Management: API Gateway. Handles the front door for REST and HTTP APIs.
- Storage: S3. For everything from static assets to logs to the data lake foundation.
- Identity: IAM for service roles, Cognito if we're handling customer-facing auth.
- Observability: CloudWatch (Logs, Metrics, Alarms) and AWS X-Ray for distributed tracing. Non-negotiable.
- Schema Management: AWS Glue Schema Registry or Confluent. Pick one and stick to it.
- Container Registry: ECR.
- **Category:** Backend Language & Runtime
- **Technology:** Golang
- **My Stance:** The backbone of our new microservice development.
- **Target Version:** Latest stable (e.g., 1.21+), but we pin the specific minor version in each project's `go.mod`.
- **Why:** Simplicity, stellar performance, first-class concurrency, and a perfect fit for cloud-native. Lean and mean, especially for Lambda.
- **Common Go-To Libraries (versions pinned in projects):**
- HTTP: `chi` is often my preference for its composability, but `gin-gonic` is also solid. Standard `net/http` if it's dead simple.
- Config: `viper`.
- Logging: `uber-go/zap` or `rs/zerolog` for structured logging. JSON output is a must.
- Kafka: `confluent-kafka-go` is robust. `segmentio/kafka-go` is an alternative.
- AWS: `aws-sdk-go-v2`.
- Testing: Go's built-in `testing` is great. `testify/assert` and `testify/mock` are standard additions. `golang-migrate` for DB schema.
- Data/SQL: Stay away from heavy ORMs in Go. `sqlx` is usually sufficient. `sqlc` for generating type-safe Go from SQL is excellent. For DynamoDB, the SDK is the way.
- **Category:** Data Serialization
- **Format:** Protobuf
- **My Stance:** The standard for Kafka messages and any gRPC communication.
- **Why:** Performance, schema evolution capabilities, and strong typing are invaluable.
- **Format:** JSON
- **My Stance:** The standard for all REST API payloads (requests/responses).
- **Why:** It's universal and human-readable.
## My Design & Style Guideposts
- **API Design (RESTful):**
- **My Stance:** Our primary style for synchronous APIs.
- **Key Tenets:**
- Stick to HTTP semantics religiously. Proper methods, proper status codes.
- Resources are plural nouns. Keep URLs clean and intuitive.
- Standardized error responses. No exceptions.
- Services must be stateless.
- `PUT`/`DELETE` must be idempotent. `POST` should be too, where it makes sense.
- Versioning via the URI (`/v1/...`). It's just simpler.
- Auth: OAuth 2.0 (Client Credentials, Auth Code) for external, JWTs internally. API Gateway authorizers are your friend.
- **Infrastructure as Code (IaC):**
- **Tool:** HashiCorp Terraform
- **My Stance:** The only way we manage infrastructure.
- **Why:** Declarative, battle-tested, and we have a solid module library built up.
- **Key Tenets:** Reusable Terraform modules are critical. State in S3 with DynamoDB locking.
- **Concurrency (Golang):**
- **My Stance:** Leverage Go's strengths but with discipline.
- **Key Tenets:** Goroutines and channels are powerful; use them wisely. Worker pools for controlled concurrency. Graceful shutdown is a must for all services.
- **Error Handling (Golang):**
- **My Stance:** Go's explicit error handling is a feature, not a bug. Embrace it.
- **Key Tenets:** Always return errors. Wrap errors with `fmt.Errorf` using `%w` (or a lib) to add context. Log errors with correlation IDs. Distinguish clearly between retryable and fatal errors.
- **Testing:**
- **My Stance:** Non-negotiable and integral to development, not an afterthought.
- **Key Tenets:**
- Unit Tests: Cover all critical logic. Mock external dependencies without mercy.
- Integration Tests: Verify interactions (e.g., service-to-DB, service-to-Kafka). Testcontainers or localstack are invaluable here.
- Contract Tests (Events): Especially for Kafka. Ensure your producers and consumers agree on the schema _before_ runtime.
- E2E Tests: For the critical business flows, API-driven.
- **Observability:**
- **My Stance:** If you can't observe it, you can't own it.
- **Key Tenets:** Structured JSON logging. Correlation IDs threaded through everything. Key operational metrics (rates, errors, latency, consumer lag) via CloudWatch. AWS X-Ray for tracing.
- **Security:**
- **My Stance:** Built-in, not bolted on. Everyone's responsibility.
- **Key Tenets:** Least privilege for all IAM roles. Secrets in AWS Secrets Manager. Rigorous input validation at all boundaries. Automated vulnerability scanning (Go modules, containers). Static analysis (`go vet`, `staticcheck`, `gosec`).
- **Development Workflow:**
- **My Stance:** Smooth, automated, and predictable.
- **Key Tenets:** Git is a given. Trunk-Based Development is generally preferred for our microservices. CI/CD (GitHub Actions, GitLab CI, or Jenkins - whatever the enterprise standard is) must be robust: lint, static analysis, all test types, build, deploy.
- Docker for local dev consistency and Fargate. Lambda gets zip packages.
## Essential Cross-Cutting Practices
- **Configuration Management:**
- **My Stance:** No magic strings or hardcoded settings in the codebase. Ever.
- **Key Tenets:** Externalize via environment variables, AWS Parameter Store, or AppConfig. Config is environment-specific.
- **Resiliency & Fault Tolerance:**
- **My Stance:** Design for failure. It _will_ happen.
- **Key Tenets:** Retries (with exponential backoff & jitter) for transient issues. Circuit breakers for flaky dependencies. DLQs for Kafka messages that just won't process. Sensible timeouts everywhere.

92
BETA-V3/docs/technical-preferences-sample-2.md Normal file
View File

@@ -0,0 +1,92 @@
# My Frontend Tech Preferences (Next.js & React)
Just some notes for myself and the AI on how I like to build my Next.js apps. Trying to keep things consistent.
## Overall Project Structure
- **`/app` directory for routing (Next.js App Router):**
- Really like this new router. Makes sense to group UI and logic by route.
- `layout.tsx` and `page.tsx` as the main files for each route.
- Loading UI: `loading.tsx` is pretty cool.
- Error UI: `error.tsx` for catching errors.
- **`/components` directory (root level):**
- For all shared/reusable React components.
- Sub-folders per component: e.g., `/components/Button/Button.tsx`, `/components/Button/Button.stories.tsx`, `/components/Button/Button.test.tsx`.
- I like to keep stories and unit tests with the component.
- **`/lib` directory (root level):**
- Helper functions, utilities, constants, type definitions that are not components.
- e.g., `lib/utils.ts`, `lib/hooks.ts`, `lib/types.ts`
- **`/styles` directory (root level):**
- Global styles in `globals.css`.
- Maybe Tailwind CSS config here if I use it (`tailwind.config.js`).
- **`/public` directory:** For static assets, as usual.
- **`/store` or `/contexts` directory (root level):**
- For state management. If using Zustand, maybe `/store/userStore.ts`. If React Context, `/contexts/ThemeContext.tsx`.
## React & Next.js Conventions
- **TypeScript Everywhere:**
- Definitely. Helps catch a lot of bugs.
- Use `interface` for public API type definitions (props), `type` for internal/utility types.
- **Functional Components with Hooks:**
- Standard practice.
- **Server Components vs. Client Components (Next.js App Router):**
- Try to use Server Components by default as much as possible for performance.
- `"use client";` only when necessary (event handlers, state, browser-only APIs).
- **Routing:**
- Next.js App Router.
- Dynamic routes with `[]` and `[... ]` folders.
- **API Routes:**
- In the `/app/api/...` folders.
- Good for small backend-for-frontend tasks.
- **State Management:**
- **Zustand:** My go-to for most global state. Simple, less boilerplate than Redux.
- **React Context:** For simpler, localized state sharing (like theme, user auth status if not too complex).
- Avoid Prop Drilling: Use Zustand or Context if props go more than 2-3 levels deep without being used.
- **Component Design:**
- Small, focused components.
- Props should be clear. Destructure props.
- Use `React.FC<Props>` for component typings.
- Fragments (`<>...</>`) when no extra DOM node is needed.
- **Styling:**
- **Tailwind CSS:** Strongly preferred. Makes styling fast and keeps HTML cleaner than tons of CSS Modules files.
- CSS Modules as a fallback or for very specific component-level styles if Tailwind isn't a good fit for some reason.
- **Environment Variables:**
- `NEXT_PUBLIC_` prefix for client-side accessible env vars.
- Standard `.env.local` for local development.
## Testing
- **E2E Testing Tool: Playwright**
- Love Playwright. It's fast and has great features (auto-waits, good selectors).
- Tests in an `/e2e` folder at the root.
- Page Object Model (POM) pattern is good for maintainable E2E tests.
- e.g., `e2e/pages/loginPage.ts`, `e2e/tests/auth.spec.ts`
- **Unit Testing: Jest & React Testing Library**
- Standard for React components.
- Focus on testing component behavior from a user's perspective, not implementation details.
- Mock API calls using `jest.mock`.
- **Integration Testing:**
- Could be a mix of Jest/RTL for testing how multiple components work together, or focused Playwright tests for small user flows.
## Other Preferred Libraries/Tools
- **Linting/Formatting:**
- ESLint with standard configs (e.g., `eslint-config-next`).
- Prettier for code formatting.
- Run on pre-commit hook (Husky + lint-staged).
- **Data Fetching:**
- Next.js built-in `fetch` (extended for server components, automatic caching).
- SWR or React Query if client-side data fetching gets complex (caching, revalidation, etc.), but try to use Server Components for data fetching first.
- **Forms:**
- React Hook Form: Good for handling forms with validation.
- Schema validation with Zod.
- **Storybook:**
- Yes, for component development and UI documentation.
- Keep stories next to components.
## Things I'm still learning/exploring:
- Advanced Next.js features (Route Handlers, Server Actions in more depth).
- More sophisticated testing strategies for server components.
- Performance optimization beyond the basics.

76
BETA-V3/docs/technical-preferences.md
View File

@@ -1,81 +1,21 @@
# User-Defined Preferred Patterns and Preferences
This document is intended for you, the user, to maintain a list of your preferred architectural patterns, design choices, technologies, or specific configurations. The Architect Agent will consult this file, when available, to understand your preferences and will aim to incorporate them into its recommendations, still seeking your confirmation.
This document is intended for you, the user, to maintain a list of your preferred architectural patterns, design choices, technologies, or specific configurations - so hopefully you do not need to suggest them every time to the PM or architect. The Architect Agent will consult this file, when available, to understand your preferences and will aim to incorporate them into its recommendations, still seeking your confirmation.
You can evolve this document over time as you discover new patterns, solidify your preferences, or wish to guide the Architect Agent more specifically for certain types of projects, platforms, languages, or architectural styles.
## How to Use This Document
- **List Your Preferences:** Add entries below detailing specific patterns, technologies, or approaches you favor.
- **Provide Context/Rationale (Optional but Recommended):** Briefly explain _why_ you prefer a certain pattern or technology. This helps the Architect Agent understand the underlying reasons and apply the preference more intelligently.
- **Specify Scope (Optional):** If a preference is specific to a certain context (e.g., "For serverless Node.js projects," "For frontend applications requiring real-time updates"), please note that.
- **Keep it Updated:** As your preferences evolve, update this document.
Remove all content aside from the first line and add anything you learn or already prefer along the way for future project reference and preference. See the examples in this folder.
## Example Preferences (Illustrative - Please Replace with Your Own)
No specific format required, but it is helpful to have sections to make it easier for the architect - possible sections include the following:
---
## Favorite Design Patterns
### General Architectural Patterns
## Testing Standards
- **Pattern:** Microservices Architecture
## Code Style Specific Preferences
- **Preference Level:** Strongly Preferred for large, complex applications.
- **Rationale:** Promotes scalability, independent deployment, and technology diversity.
- **Notes:** Consider event-driven communication (e.g., Kafka, RabbitMQ) for inter-service communication where appropriate.
## Tech Stack to Use
- **Pattern:** Hexagonal Architecture (Ports and Adapters)
- **Preference Level:** Preferred for core business logic components.
- **Rationale:** Enhances testability and decouples business logic from infrastructure concerns.
---
### Technology Preferences
- **Category:** Cloud Provider
- **Technology:** AWS (Amazon Web Services)
- **Preference Level:** Preferred
- **Rationale:** Familiarity with the ecosystem, extensive service offerings.
- **Specific Services to Favor (if applicable):**
- Compute: Lambda for serverless, EC2 for general purpose, EKS for Kubernetes.
- Database: RDS (PostgreSQL), DynamoDB.
- Storage: S3.
- **Category:** Backend Language/Framework
- **Technology:** Python with FastAPI
- **Preference Level:** Strongly Preferred for new API development.
- **Rationale:** Performance, ease of development, modern features.
- **Category:** Frontend Framework
- **Technology:** React with TypeScript
- **Preference Level:** Preferred
- **Rationale:** Component-based architecture, strong community support, type safety.
---
### Design Choices & Styles
- **Factories and Facades:** Especially for third party APIs or libraries
- Use Facades around APIs, when unit testing a file that uses the facade, mock the facade. when testing the facade, if its a library do not mock the library. if its an api, intercept the requests and mock the responses.
- **Topic:** API Design
- **Style:** RESTful APIs
- **Preference Level:** Preferred
- **Notes:** Adhere to standard HTTP methods, clear resource naming, and consistent error handling. Consider OpenAPI for documentation.
- Handlers should only deal with request and response concerns and pass off to a controller for business logic.
- **Topic:** Infrastructure as Code (IaC)
- **Tool:** Terraform
- **Preference Level:** Strongly Preferred
- **Rationale:** Cloud-agnostic, declarative syntax, strong community.
---
_(Add your own preferences below this line. You can copy and modify the structure of the examples above or create your own format.)_
## Your Preferences:
_(Start adding your preferences here...)_
## etc...