This is cool, I have been working with something in a similar vein (https://github.com/wlach/idr-tools), though it seems like you emphasize keeping a decision log more than I do. For me, that aspect has been a lot less useful than structuring my thoughts about how implementation should proceed. It probably depends a lot on what you're trying to do.
This might be my bias, but I feel like the site doesn't really immediately answer the question of why I would want to use these? What nagging issue does it solve? Some real world examples and case studies would go a long way to answering those questions. The theoretical stuff (papers, prior art, etc.) looks interesting but IMO does not belong on the front page.
show comments
varyherb
It sounds like a good idea, but having used this approach in a professional codebase with dozens of contributors, I can tell you firsthand it will start to degrade the code you get from a model surprisingly quickly. The agent will start to feel confused by the various conflicting "guardrails" and "constraints" the ADR is supposedly documenting. You will ask the agent why it did a particular contrived thing and it will cite various flawed or outdated assumptions.
It's the same old problem of doc rot, but now the docs are blindly obeyed. It sounds simple to just keep the docs up-to-date, especially with AI, but that approach results in an unreadable AI slop trough.
I'm still unsure what to recommend instead, especially in a collaborative setting.
show comments
diegof79
The title got me interested. However, I couldn’t bear your site, sorry.
My feedback: cut the slop. I see a wall of text with explanations that are full of marketing phrases, filler sentences, and there isn’t a clear, curated explanation.
Again, sorry for my blunt feedback.
show comments
kensuh
I really resonate with this since we do pretty much the same thing. If the same notes keep coming up during reviews, a human defines a single design rule, documents that call, and carries it over to the next round.
Such as "intent.md"! search it
ethanj8011
Megaslop. I stopped reading at "Your thinking stops disappearing. Your decisions start compounding."
Like what even is this, we know about ADRs, this is a common framework.
show comments
dazzeloid
very cool. do you think of this primarily for engineering work or more generally collaborating with AI?
show comments
ozozozd
Tell what this does like you are telling w friend who trusts what you say, without the layers and layers of slop that aims to establish trust.
Please.
4b11b4
wait over a year?
What were the design decisions which you have settled on and what did you throw out?
show comments
deaux
> I would like feedback on the onboarding, on what you make of the currently online materials, and how I could make any of this clearer. Thanks!
Currently the page is a lot of slop text without the main question most people who know what ADRs are and might be interested will have: what are the main differences and what do you see as the main advantages over other existing systems that use ADRs, the most popular one being Matt Pocock's?
You need to realize that there are thousands of projects like these. Most people who are in your target audience is already using something similar, so it needs to be instantly clear what the difference is. You've got 5 seconds and having to scroll through slop takes up most of those. Just being realistic here.
This is cool, I have been working with something in a similar vein (https://github.com/wlach/idr-tools), though it seems like you emphasize keeping a decision log more than I do. For me, that aspect has been a lot less useful than structuring my thoughts about how implementation should proceed. It probably depends a lot on what you're trying to do.
This might be my bias, but I feel like the site doesn't really immediately answer the question of why I would want to use these? What nagging issue does it solve? Some real world examples and case studies would go a long way to answering those questions. The theoretical stuff (papers, prior art, etc.) looks interesting but IMO does not belong on the front page.
It sounds like a good idea, but having used this approach in a professional codebase with dozens of contributors, I can tell you firsthand it will start to degrade the code you get from a model surprisingly quickly. The agent will start to feel confused by the various conflicting "guardrails" and "constraints" the ADR is supposedly documenting. You will ask the agent why it did a particular contrived thing and it will cite various flawed or outdated assumptions.
It's the same old problem of doc rot, but now the docs are blindly obeyed. It sounds simple to just keep the docs up-to-date, especially with AI, but that approach results in an unreadable AI slop trough.
I'm still unsure what to recommend instead, especially in a collaborative setting.
The title got me interested. However, I couldn’t bear your site, sorry.
My feedback: cut the slop. I see a wall of text with explanations that are full of marketing phrases, filler sentences, and there isn’t a clear, curated explanation.
Again, sorry for my blunt feedback.
I really resonate with this since we do pretty much the same thing. If the same notes keep coming up during reviews, a human defines a single design rule, documents that call, and carries it over to the next round.
Such as "intent.md"! search it
Megaslop. I stopped reading at "Your thinking stops disappearing. Your decisions start compounding."
Like what even is this, we know about ADRs, this is a common framework.
very cool. do you think of this primarily for engineering work or more generally collaborating with AI?
Tell what this does like you are telling w friend who trusts what you say, without the layers and layers of slop that aims to establish trust.
Please.
wait over a year?
What were the design decisions which you have settled on and what did you throw out?
> I would like feedback on the onboarding, on what you make of the currently online materials, and how I could make any of this clearer. Thanks!
Currently the page is a lot of slop text without the main question most people who know what ADRs are and might be interested will have: what are the main differences and what do you see as the main advantages over other existing systems that use ADRs, the most popular one being Matt Pocock's?
You need to realize that there are thousands of projects like these. Most people who are in your target audience is already using something similar, so it needs to be instantly clear what the difference is. You've got 5 seconds and having to scroll through slop takes up most of those. Just being realistic here.