Ask
29

I correct the same three things in every generated diff - what do you actually put in the repo so it stops?

Every session I end up saying the same things. We do not use that logging library. Tests go in this directory, not next to the source. Do not add a comment above every line.

I say it, the session gets it right, and the next session starts from nothing.

I know there is a convention of putting instructions in a file in the repo and I have made a half-hearted attempt - a long document that I am fairly sure is being skimmed rather than followed, because the same three things still come back.

What actually works? I would rather write one good file than keep repeating myself, and I would like to know why my current one is not doing the job.

3 answers Share
Report

Answering anonymously, a moderator will review it first.

  • @make_it_checkable · 3w ago

    The higher-leverage version of your problem: a rule that a tool can enforce should be enforced by the tool, not written in a document.

    Of your three complaints, two are almost certainly automatable:

    The wrong logging library, a lint rule banning the import, with a message saying what to use instead. Then it is caught in seconds, by the same check that catches it for humans, and the correction arrives as an error rather than as a review comment.

    Tests in the wrong directory, a structural check, or simply a test runner configuration that only looks in the right place, so misplaced tests visibly do not run.

    Comment density is a taste thing and belongs in the document.

    The reason this matters beyond convenience: prose instructions compete with everything else in the context, and a check does not. A failing command is unambiguous and self-correcting. A line in a document is one instruction among fifty.

    It also fixes the problem for the humans on the team, and it keeps working when the model changes.

    So the order I would go in: automate what is automatable, write down what is genuinely contextual, and keep the written part short enough that it is read rather than skimmed.

    26
    Share
    Reply

    Answering anonymously, a moderator will review it first.

    Report
  • @write_it_down_once · 3w ago

    Your document is probably long, general and full of things that were already obvious. That is the usual failure and it is fixable.

    What earns its place in a repo instructions file:

    Things that are true here and not elsewhere. Which logging library, where tests live, which package manager, how to run the suite, the one directory that looks unused and is not. Nothing about writing clean code: that is generic and it is noise.

    Decisions with a reason attached. We use X rather than Y because of Z. The reason matters, because it lets a reader generalise instead of pattern-matching one instruction.

    The traps. The file that looks safe to edit and is generated. The test that must be run before committing. The migration that must not be edited. These are the highest-value lines in the whole file.

    Commands, verbatim. How to build, test and run. Exactly, not approximately.

    What to cut:

    Anything a linter enforces. If a rule is checked automatically, it does not need prose: see the next answer.

    Style preferences with no consequence.

    A tour of the architecture. Interesting, rarely acted on, and it is what makes the file long enough to skim.

    Aim for something a new colleague could read in three minutes. That is roughly the right size for a model too.

    30
    Share
    Reply

    Answering anonymously, a moderator will review it first.

    Report
  • @scope_the_context · 3w ago

    Two structural things that helped once the file itself was good.

    Put instructions near what they govern. A repo-wide file for repo-wide things, and a short file inside a directory for rules specific to that directory. A rule about how the API layer is structured is much more likely to be applied when it is next to the API layer than when it is on page two of a root document.

    Keep it current, and delete aggressively. An instructions file accumulates. Lines about a library you removed, a process you abandoned, a directory that no longer exists. Stale instructions are worse than no instructions because they teach the wrong thing confidently, and they make the whole file less trustworthy.

    A habit worth having: when you correct something in a session for the second time, that is the trigger to write it down. Not the first time, which is often a one-off. The second time is a pattern.

    And the inverse: when you notice a line in the file has not been relevant for months, cut it.

    One last thing on your specific case: after you write it, test it. Start a fresh session, ask for something that would previously have triggered one of the three mistakes, and see whether it happens. If it still does, the line is not clear enough or the file is too long, and you will find out in two minutes rather than over a fortnight.

    1
    Share
    Reply

    Answering anonymously, a moderator will review it first.

    Report