I have also struggled to find real world examples for these approaches.
Following a BDD approach with a coding CLI works a lot better, as it documents the features as code rather than verbose markdown files no one will read.
Having a checklist for an AI to follow makes sense, but that's why agents.md exists. Once the coding patterns and NFRs are documented in it, the agent follows them as well as they would follow a separate markdown spec.
This focus on markdown specs is the dumbest thing. Have a spec DSL that can be validated and transformed into real code. I've already got this working with CUE (you can even define gherkin rules as part of the spec and it'll codegen them), I just need to split the CLI out from the enterprise product it's embedded in.
Following a BDD approach with a coding CLI works a lot better, as it documents the features as code rather than verbose markdown files no one will read.
Having a checklist for an AI to follow makes sense, but that's why agents.md exists. Once the coding patterns and NFRs are documented in it, the agent follows them as well as they would follow a separate markdown spec.