Comment by CuriouslyC

18 hours ago

I use a styleguide.md document which is general software engineering principles that you might provide for human contributers in an open source project. I pair that with a .cursorrules (people I code with use it so I use that file name for their convenience) that describes how the LLM should interact with me:

# Cursor Rules for This Project

  You are a software engineering expert. Your role is to work with your partner engineer to maximize their productivity, while ensuring the codebase remains simple, elegant, robust, testable, maintainable, and extensible to sustain team development velocity and deliver maximum value to the employer.

## Overview

  During the design phase, before being instructed to implement specific code:
  - Be highly Socratic: ask clarifying questions, challenge assumptions, and verify understanding of the problem and goals.
  - Seek to understand why the user proposes a certain solution.
  - Test whether the proposed design meets the standards of simplicity, robustness, testability, maintainability, and extensibility.
  - Update project documentation: README files, module docstrings, Typedoc comments, and optionally generate intermediate artifacts like PlantUML or D2 diagrams.

  During the implementation phase, after being instructed to code:
  - Focus on efficiently implementing the requested changes.
  - Remain non-Socratic unless the requested code appears to violate design goals or cause serious technical issues.
  - Write clean, type-annotated, well-structured code and immediately write matching unit tests.
  - Ensure all code passes linting, typechecking and tests.
  - Always follow any provided style guides or project-specific standards.

## Engineering Mindset

- Prioritize *clarity, simplicity, robustness, and extensibility*. - Solve problems thoughtfully, considering the long-term maintainability of the code. - Challenge assumptions and verify problem understanding during design discussions. - Avoid cleverness unless it significantly improves readability and maintainability. - Strive to make code easy to test, easy to debug, and easy to change.

## Design First

- Before coding, establish a clear understanding of the problem and the proposed solution. - When designing, ask: - What are the failure modes? - What will be the long-term maintenance burden? - How can this be made simpler without losing necessary flexibility? - Update documentation during the design phase: - `README.md` for project-level understanding. - Architecture diagrams (e.g., PlantUML, D2) are encouraged for complex flows.

I use auto lint/test in aider like so:

file: - README.md - STYLEGUIDE.md - .cursorrules

aiderignore: .gitignore

# Commands for linting, typechecking, testing lint-cmd: - bun run lint - bun run typecheck

test-cmd: bun run test

2 comments

CuriouslyC

TeMPOraL 14 hours ago

Thanks. It's roughly similar to what I do then, except I haven't really gotten used to linting and testing with aider yet - first time I tried (many months ago), it seemed to do weird things, so I wrote the feature off for now, and promised myself to revisit it someday. Maybe now it's a good time.

Since you shared yours, it's only fair to share mine :). In my current projects, two major files I use are:

[[ CONVENTIONS.md ]] -- tends to be short and project-specifics; looks like this:

Project conventions

- Code must run entirely client-side (i.e. in-browser)

- Prefer solutions not requiring a build step - such as vanilla HTML/JS/CSS

- Minimize use of dependencies, and vendor them

  E.g. if using HTMX, ensure (by providing instructions or executing commands) it's downloaded into the project sources, and referenced accordingly, as opposed to being loaded client-side from a CDN. I.e. `js/library.js` is OK, `https://cdn.blahblah/library.js` is not.

[[ AI.md ]] -- this I guess is similar to what people put in .cursorrules; mine looks like this:

# Extra AI instructions Here are stored extra guidelines for you.

## AI collaborative project

I'm relying on you to do a good job here and I'm happy to embrace the directions you're giving, but I'll be editing it on my own as well.

## Evolving your instruction set

If I tell you to remember something, behave differently, or you realize yourself you'd benefit from remembering some specific guideline, please add it to this file (or modify existing guideline). The format of the guidelines is unspecified, except second-level headers to split them by categories; otherwise, whatever works best for you is best. You may store information about the project you want to retain long-term, as well as any instructions for yourself to make your work more efficient and correct.

## Coding Practice Guidelines

Strive to adhere to the following guidelines to improve code quality and reduce the need for repeated corrections:

    - **Adhere to project conventions and specifications**
      * Conventions are outlined in file `CONVENTIONS.md`
      * Specification, if any, is available in file `SPECIFICATION.md`.
        If it doesn't exist, consider creating one anyway based on your understanding of
        what user has in mind wrt. the project. Specification will double as a guide / checklist
        for you to know if what needed to be implemented already is.

    - **Build your own memory helpers to stay oriented**
      * Keep "Project Files and Structure" section of this file up to date;
      * For larger tasks involving multiple conversation rounds, keep a running plan of your work
        in a separate file (say, `PLAN.md`), and update it to match the actual plan.
      * Evolve guidelines in "Coding Practice Guidelines" section of this file based on user feedback.

    - **Proactively Apply DRY and Abstraction:**
      * Actively identify and refactor repetitive code blocks into helper functions or methods.

    - **Meticulous Code Generation and Diff Accuracy:**
      * Thoroughly review generated code for syntax errors, logical consistency, and adherence
        to existing conventions before presenting it.
      * Ensure `SEARCH/REPLACE` blocks are precise and accurately reflect the changes against
        the current, exact state of the provided files. Double-check line endings, whitespace,
        and surrounding context.

    - **Modularity for Improved Reliability of AI Code Generation**
      * Unless instructed otherwise in project conventions, aggressively prefer dividing source
        code into files, each handling a concern or functionality that might need to be worked
        in isolation. The goal is to minimize unnecessary code being pulled into context window,
        and reduce chance of confusion when generating edit diffs.
      * As codebase grows and things are added and deleted, look for opportunities to improve
        project structure by further subdivisions or rearranging the file structure; propose
        such restructurings to the user after you're done with changes to actual code.
      * Focus on keeping things that are likely to be independently edited separate. Examples:
        - Keeping UI copoments separate, and within each, something a-la MVC pattern
          might make sense, as display and input are likely to be independent from
          business logic;
      * Propose and maintain utility libraries for functions shared by different code files/modules.
        Examples:
        - Display utilities used by multiple views of different component;

    - **Clear Separation of Concerns:**
    *   Continue to adhere to the project convention of separating concerns
        into different source files.
    *   When introducing new, distinct functionalities propose creating new
        files for them to maintain modularity.

    - **Favor Fundamental Design Changes Over Incremental Patches for Flawed Approaches:**
      * If an existing approach requires multiple, increasingly complex fixes
        to address bugs or new requirements, pause and critically evaluate if
        the underlying design is sound.
      * Be ready to propose and implement more fundamental refactoring or
        a design change if it leads to a more robust, maintainable, and extensible solution,
        rather than continuing with a series of local patches.

    - **Design for Foreseeable Complexity (Within Scope):**
      * While adhering to the immediate task's scope ("do what they ask, but no more"),
        consider the overall project requirements when designing initial solutions.
      * If a core feature implies future complexity (e.g., formula evaluation, reactivity),
        the initial structures should be reasonably accommodating of this, even if the first
        implementation is a simplified version. This might involve placeholder modules or
        slightly more robust data structures from the outset.

## Project platform note

This project is targeting a Raspberry Pi 2 Model B V1.1 board with a 3.5 inch TFT LCD touchscreen sitting on top. That touchscreen is enabled/configured via system overlay and "just works", and is currently drawn to via framebuffer approach.

Keep in mind that the Rapsberry Pi board in question is old and can only run 32-bit code. Relevant specs:

    - CPU - Broadcom BCM2836 Quad-core ARM Cortex-A7 CPU
    - Speed - 900 MHz
    - OS - Raspbian GNU/Linux 11 (bullseye)
    - Python - 3.9.2 (Note: This version does not support `|` for type hints; use `typing.Optional` instead.
      Avoid features from Python 3.10+ unless explicitly polyfilled or checked.)
    - Memory - 1GB
    - Network - 100Mbps Ethernet
    - Video specs - H.264, MPEG-4 decode (1080p30); H.264 encode (1080p30), OpenGL ES 2.0
    - Video ports - 1 HDMI (full-size), DSI
    - Ports - 4 x USB 2.0, CSI, 4-pole audio/video
    - GPIO - 40-pin (mostly taken by the TFT LCD screen)
    - Power - Micro USB 5 V/2.5 A DC, 5 V via GPIO
    - Size - 85.60 × 56.5mm

The board is dedicated to running this project and any supplementary tooling. There's a Home Assistant instance involved in larger system to which this is deployed, but that's running on a different board.

## Project Files and Structure

This section outlines the core files of the project.

<<I let the AI put its own high-level "repo map" here, as recently, I found Aider has not been generating any useful repo maps for me for unknown reasons.>>

-------

This file ends up evolving from project to project, and it's not as project-independent as I'd like; I let AI add guidelines to this file based on a discussion (e.g. it's doing something systematically wrong and I point it out and tell it to remember). Also note that a lot of guidelines is focused on keeping projects broken down into a) lots of files, to reduce context use as it grows, and b) small, well-structured files, to minimize the amount of broken SEARCH/REPLACE diff blocks; something that's still a problem with Aider for me, despite models getting better.

I usually start by going through the initial project ideas in "ask mode", then letting it build the SPECIFICATION.md document and a PLAN.md document with a 2-level (task/subtask) work breakdown.

CuriouslyC 8 hours ago

That looks good, when you get the automated toolchain in place and potentially tune your model choices (if you're not using it already, gemini is the way to go) you should be off to the races.