fixups in formatting; minor other stuff.
This commit is contained in:
Nicole Dresselhaus
421
dist/Writing/coding-age-ai.html
vendored
421
dist/Writing/coding-age-ai.html
vendored
@ -739,17 +739,17 @@ div.csl-indent {
|
||||
|
||||
<section id="introduction" class="level2 page-columns page-full">
|
||||
<h2 class="anchored" data-anchor-id="introduction">Introduction</h2>
|
||||
<p>In the fast eveolving field of AI there is a clear lack of reports on “what really works”. Some techniques hailed as revolution (like the DeepSeek Aha-Moment<span class="citation" data-cites="DeepSeek-AI2025DeepSeekR1IncentivizingReasoning">[<a href="#ref-DeepSeek-AI2025DeepSeekR1IncentivizingReasoning" role="doc-biblioref">1</a>]</span>) for unlimited potential were soon realized to “just” optimize nieche problems that can benchmarked<span class="citation" data-cites="Shao2025SpuriousRewardsRethinking">[<a href="#ref-Shao2025SpuriousRewardsRethinking" role="doc-biblioref">2</a>]</span><a href="#fn1" class="footnote-ref" id="fnref1" role="doc-noteref"><sup>1</sup></a>.</p>
|
||||
<div class="no-row-height column-margin column-container"><div id="fn1"><p><sup>1</sup> Like all decent humans i ain’t got time to read up on everything - so a big shoutout to <span class="citation" data-cites="bycloud2025LLMsRLRevelation">[<a href="#ref-bycloud2025LLMsRLRevelation" role="doc-biblioref">3</a>]</span> for doing thorough reviews on ML-topics and linking the respective papers!</p></div><div id="fn2"><p><sup>2</sup> i.e. the “base model” nearly all papers tested their finding on (qwen-series) also gets better with RLVR-optimization if rewards are random instead of verified</p></div></div><p>I personally think it is an exercise in futility to get a <em>current</em> theoretical overview for forming a decent grounded opinion on the state of things. Even before one is done analyzing the literature, crossrefercencing and collecting evidence and then finally formulating methods and implementing them, the next revolution comes around that could put everything on its head again. In the afromentioned example the community went from “Reasoning is the solution” in January<span class="citation" data-cites="DeepSeek-AI2025DeepSeekR1IncentivizingReasoning">[<a href="#ref-DeepSeek-AI2025DeepSeekR1IncentivizingReasoning" role="doc-biblioref">1</a>]</span> over first critical views in March<span class="citation" data-cites="Liu2025UnderstandingR1ZeroLikeTraining">[<a href="#ref-Liu2025UnderstandingR1ZeroLikeTraining" role="doc-biblioref">4</a>]</span> to doubts on that claims validity of generating concepts previously not present in the base model in May<span class="citation" data-cites="Mukherjee2025ReinforcementLearningFinetunes">[<a href="#ref-Mukherjee2025ReinforcementLearningFinetunes" role="doc-biblioref">5</a>]</span> to complete ad-absurdum in June<span class="citation" data-cites="Shao2025SpuriousRewardsRethinking">[<a href="#ref-Shao2025SpuriousRewardsRethinking" role="doc-biblioref">2</a>]</span><a href="#fn2" class="footnote-ref" id="fnref2" role="doc-noteref"><sup>2</sup></a>.</p>
|
||||
<p>Therefore see this “Field Guide” for what it is: A current state of things that work for at least 1 individuum in exactly this ecosystem at this point in time.</p>
|
||||
<p>In the fast evolving field of AI there is a clear lack of reports on “what really works”. Some techniques hailed as revolution (like the DeepSeek Aha-Moment<span class="citation" data-cites="DeepSeek-AI2025DeepSeekR1IncentivizingReasoning">[<a href="#ref-DeepSeek-AI2025DeepSeekR1IncentivizingReasoning" role="doc-biblioref">1</a>]</span>) for unlimited potential were soon realized to “just” optimize niche problems that can benchmarked<span class="citation" data-cites="Shao2025SpuriousRewardsRethinking">[<a href="#ref-Shao2025SpuriousRewardsRethinking" role="doc-biblioref">2</a>]</span><a href="#fn1" class="footnote-ref" id="fnref1" role="doc-noteref"><sup>1</sup></a>.</p>
|
||||
<div class="no-row-height column-margin column-container"><div id="fn1"><p><sup>1</sup> Like all decent humans i ain’t got time to read up on everything - so a big shoot-out to <span class="citation" data-cites="bycloud2025LLMsRLRevelation">[<a href="#ref-bycloud2025LLMsRLRevelation" role="doc-biblioref">3</a>]</span> for doing thorough reviews on ML-topics and linking the respective papers!</p></div><div id="fn2"><p><sup>2</sup> i.e. the “base model” nearly all papers tested their finding on (qwen-series) also gets better with RLVR-optimization if rewards are random instead of verified</p></div></div><p>I personally think it is an exercise in futility to get a <em>current</em> theoretical overview for forming a decent grounded opinion on the state of things. Even before one is done analyzing the literature, crossrefercencing and collecting evidence and then finally formulating methods and implementing them, the next revolution comes around that could put everything on its head again. In the afromentioned example the community went from “Reasoning is the solution” in January<span class="citation" data-cites="DeepSeek-AI2025DeepSeekR1IncentivizingReasoning">[<a href="#ref-DeepSeek-AI2025DeepSeekR1IncentivizingReasoning" role="doc-biblioref">1</a>]</span> over first critical views in March<span class="citation" data-cites="Liu2025UnderstandingR1ZeroLikeTraining">[<a href="#ref-Liu2025UnderstandingR1ZeroLikeTraining" role="doc-biblioref">4</a>]</span> to doubts on that claims validity of generating concepts previously not present in the base model in May<span class="citation" data-cites="Mukherjee2025ReinforcementLearningFinetunes">[<a href="#ref-Mukherjee2025ReinforcementLearningFinetunes" role="doc-biblioref">5</a>]</span> to complete ad-absurdum in June<span class="citation" data-cites="Shao2025SpuriousRewardsRethinking">[<a href="#ref-Shao2025SpuriousRewardsRethinking" role="doc-biblioref">2</a>]</span><a href="#fn2" class="footnote-ref" id="fnref2" role="doc-noteref"><sup>2</sup></a>.</p>
|
||||
<p>Therefore see this “Field Guide” for what it is: A current state of things that work for at least 1 Individuum in exactly this ecosystem at this point in time.</p>
|
||||
</section>
|
||||
<section id="how-to-program-with-cursor" class="level2">
|
||||
<h2 class="anchored" data-anchor-id="how-to-program-with-cursor">How to program with Cursor</h2>
|
||||
<p>In essence <a href="https://cursor.com">Cursor</a> is “just” a fork of <a href="https://code.visualstudio.com/">Microsofts VSCode</a> with some added functionality: Automatically injecting files into LLM-Prompts, offering tool-aware LLMs to use <a href="https://modelcontextprotocol.io/introduction">MCP</a>s, read the filesystem, execute arbitrary commands in the shell (either automomatically or after permission), getting feedback from the editor (i.e. installed linters, language-servers etc.) and thus have the same (or even better) information/tools available as the programmer in front of the screen.</p>
|
||||
<p>In essence <a href="https://cursor.com">Cursor</a> is “just” a fork of <a href="https://code.visualstudio.com/">Microsofts VSCode</a> with some added functionality: Automatically injecting files into LLM-Prompts, offering tool-aware LLMs to use <a href="https://modelcontextprotocol.io/introduction">MCP</a>s, read the filesystem, execute arbitrary commands in the shell (either automatically or after permission), getting feedback from the editor (i.e. installed linters, language-servers etc.) and thus have the same (or even better) information/tools available as the programmer in front of the screen.</p>
|
||||
<section id="capabilities-general-procedure" class="level3">
|
||||
<h3 class="anchored" data-anchor-id="capabilities-general-procedure">Capabilities / General procedure</h3>
|
||||
<p>The main issue is now: theoretically agentic IDEs can get all information - practically it is limited directly by token-window sizes, costs of these queries; and indirectly by outsourced costs like environmental impacts, data-security, etc. The suppliers of such services can claim privacy as much as they want - it can’t be proven and (especially under US-Law) is not even possible to resist lawful orders (including the gag-order to not talk about these).</p>
|
||||
<p>In practise one feels the direct pain points more severly. Some regular examples include generating redundant code, because the current context was not aware of utility-modules and functions it could use - leading to huge technical debt in no time.</p>
|
||||
<p>In practise one feels the direct pain points more severely. Some regular examples include generating redundant code, because the current context was not aware of utility-modules and functions it could use - leading to huge technical debt in no time.</p>
|
||||
<p>Therefore my preferred workflow is to “think bigger”. Imagine being a product owner of a huge, sluggish company. The left hand never knows what the right hand does or has done (i.e. the LLM forgetting things already exist in the codebase), everything has to be rigorous defined, specified and enforced. Some people reported good results with Test-Driven-Development (TDD) - but in my experience these things only prevent regressions and not proactively enforce the desired agent behaviour.</p>
|
||||
</section>
|
||||
<section id="lessons-from-project-management" class="level3">
|
||||
@ -764,9 +764,9 @@ This could be a bug, a feature, some changes to existing behaviour etc.</li>
|
||||
This dives into the codebase to asses the current state of things. Maybe some bugs are obvious and easily fixed.<br>
|
||||
This formalizes that the LLM understood what <em>should</em> be done and especially what is <em>out of scope</em>.</li>
|
||||
<li>Pin the desired behaviour in a <strong>Specification</strong>.<br>
|
||||
Either this means changing currently established specifications (i.e. bug/chang) or writing complete new ones (i.e. feature).</li>
|
||||
Either this means changing currently established specifications (i.e. bug/change) or writing complete new ones (i.e. feature).</li>
|
||||
<li>Investigate <strong>Spec-Compliance</strong>.<br>
|
||||
Again the agentlooks at the codebase to identify <em>where</em> things should change and <em>how</em>. Also recommendation are made on how it could achieve the goal.</li>
|
||||
Again the agent looks at the codebase to identify <em>where</em> things should change and <em>how</em>. Also recommendation are made on how it could achieve the goal.</li>
|
||||
<li>Generate <strong>Tasks</strong>.<br>
|
||||
From the compliance-report of spec-deviations (either from a bug or from a new/changed spec) finally a Plan to fix everything can be derived (think: Sprint-Planning).</li>
|
||||
<li><strong>NOTE: Up to here the agent never touched the code.</strong></li>
|
||||
@ -839,39 +839,58 @@ This is most often the most trivial step. Everything is known and formulated for
|
||||
<span id="cb2-13"><a href="#cb2-13" aria-hidden="true" tabindex="-1"></a></span>
|
||||
<span id="cb2-14"><a href="#cb2-14" aria-hidden="true" tabindex="-1"></a><span class="fu">### Output</span></span>
|
||||
<span id="cb2-15"><a href="#cb2-15" aria-hidden="true" tabindex="-1"></a></span>
|
||||
<span id="cb2-16"><a href="#cb2-16" aria-hidden="true" tabindex="-1"></a>• Create /tasks/<span class="dt"><</span><span class="kw">feature</span><span class="dt">></span>/PRD.md • Markdown only – no prose, no code‑fences. •</span>
|
||||
<span id="cb2-17"><a href="#cb2-17" aria-hidden="true" tabindex="-1"></a>File structure: # <span class="dt"><</span><span class="kw">Feature</span><span class="ot"> title</span><span class="dt">></span> ## 1. Problem / Motivation ## 2. Goals ## 3.</span>
|
||||
<span id="cb2-18"><a href="#cb2-18" aria-hidden="true" tabindex="-1"></a>Non‑Goals ## 4. Target Users & Personas ## 5. User Stories (Gherkin</span>
|
||||
<span id="cb2-19"><a href="#cb2-19" aria-hidden="true" tabindex="-1"></a>“Given/When/Then”) ## 6. Acceptance Criteria ## 7. Technical Notes /</span>
|
||||
<span id="cb2-20"><a href="#cb2-20" aria-hidden="true" tabindex="-1"></a>Dependencies ## 8. Open Questions</span>
|
||||
<span id="cb2-21"><a href="#cb2-21" aria-hidden="true" tabindex="-1"></a></span>
|
||||
<span id="cb2-22"><a href="#cb2-22" aria-hidden="true" tabindex="-1"></a><span class="fu">### Process</span></span>
|
||||
<span id="cb2-23"><a href="#cb2-23" aria-hidden="true" tabindex="-1"></a></span>
|
||||
<span id="cb2-24"><a href="#cb2-24" aria-hidden="true" tabindex="-1"></a><span class="ss">1. </span>Stakeholder provides a single‑sentence feature idea and invokes this rule.</span>
|
||||
<span id="cb2-25"><a href="#cb2-25" aria-hidden="true" tabindex="-1"></a><span class="ss">2. </span>Look at specifications in <span class="in">`specs/`</span> and inspect the code if needed to get an</span>
|
||||
<span id="cb2-26"><a href="#cb2-26" aria-hidden="true" tabindex="-1"></a> idea what the Stakeholder expects from this feature.</span>
|
||||
<span id="cb2-27"><a href="#cb2-27" aria-hidden="true" tabindex="-1"></a><span class="ss">3. </span>Ask up to five clarifying questions (Q1 … Q5). If anything is still vague</span>
|
||||
<span id="cb2-28"><a href="#cb2-28" aria-hidden="true" tabindex="-1"></a> after five, look into the project with the new information provided. You may</span>
|
||||
<span id="cb2-29"><a href="#cb2-29" aria-hidden="true" tabindex="-1"></a> ask for further clarification up to 3 times following this schema, else flag</span>
|
||||
<span id="cb2-30"><a href="#cb2-30" aria-hidden="true" tabindex="-1"></a> it in _Open Questions_.</span>
|
||||
<span id="cb2-31"><a href="#cb2-31" aria-hidden="true" tabindex="-1"></a><span class="ss">4. </span>After questions are answered reply exactly: Ready to generate the PRD.</span>
|
||||
<span id="cb2-32"><a href="#cb2-32" aria-hidden="true" tabindex="-1"></a><span class="ss">5. </span>On a user message that contains only the word "go" (case‑insensitive): •</span>
|
||||
<span id="cb2-33"><a href="#cb2-33" aria-hidden="true" tabindex="-1"></a> Generate /tasks/<span class="dt"><</span><span class="kw">feature</span><span class="dt">></span>/PRD.md following _Output_ spec. • Reply:</span>
|
||||
<span id="cb2-34"><a href="#cb2-34" aria-hidden="true" tabindex="-1"></a> <span class="dt"><</span><span class="kw">feature</span><span class="dt">></span>/PRD.md created – review it.</span>
|
||||
<span id="cb2-35"><a href="#cb2-35" aria-hidden="true" tabindex="-1"></a><span class="ss">6. </span>STOP. Do **not** generate tasks or code in this rule.</span>
|
||||
<span id="cb2-36"><a href="#cb2-36" aria-hidden="true" tabindex="-1"></a></span>
|
||||
<span id="cb2-37"><a href="#cb2-37" aria-hidden="true" tabindex="-1"></a><span class="fu">### Writing guidelines</span></span>
|
||||
<span id="cb2-38"><a href="#cb2-38" aria-hidden="true" tabindex="-1"></a></span>
|
||||
<span id="cb2-39"><a href="#cb2-39" aria-hidden="true" tabindex="-1"></a>• Keep each bullet ≤120 characters. • Use action verbs and measurable language.</span>
|
||||
<span id="cb2-40"><a href="#cb2-40" aria-hidden="true" tabindex="-1"></a>• Leave TBDs only in _Open Questions_. • No business fluff – pretend the reader</span>
|
||||
<span id="cb2-41"><a href="#cb2-41" aria-hidden="true" tabindex="-1"></a>is a junior developer.</span>
|
||||
<span id="cb2-42"><a href="#cb2-42" aria-hidden="true" tabindex="-1"></a></span>
|
||||
<span id="cb2-43"><a href="#cb2-43" aria-hidden="true" tabindex="-1"></a><span class="fu">### Safety rails</span></span>
|
||||
<span id="cb2-44"><a href="#cb2-44" aria-hidden="true" tabindex="-1"></a></span>
|
||||
<span id="cb2-45"><a href="#cb2-45" aria-hidden="true" tabindex="-1"></a>• Assume all work happens in a non‑production environment, unless otherwise</span>
|
||||
<span id="cb2-46"><a href="#cb2-46" aria-hidden="true" tabindex="-1"></a>stated or requested by you. • Do not include sensitive data or credentials in</span>
|
||||
<span id="cb2-47"><a href="#cb2-47" aria-hidden="true" tabindex="-1"></a>the PRD. • Check the generated Document with <span class="in">`markdownlint`</span> (if available),</span>
|
||||
<span id="cb2-48"><a href="#cb2-48" aria-hidden="true" tabindex="-1"></a>apply auto-fixes and fix the remaining issues manually.</span></code><button title="In die Zwischenablage kopieren" class="code-copy-button"><i class="bi"></i></button></pre></div>
|
||||
<span id="cb2-16"><a href="#cb2-16" aria-hidden="true" tabindex="-1"></a><span class="ss">- </span>Create /tasks/<span class="dt"><</span><span class="kw">feature</span><span class="dt">></span>/PRD.md</span>
|
||||
<span id="cb2-17"><a href="#cb2-17" aria-hidden="true" tabindex="-1"></a><span class="ss">- </span>Markdown only – no prose, no code‑fences.</span>
|
||||
<span id="cb2-18"><a href="#cb2-18" aria-hidden="true" tabindex="-1"></a><span class="ss">- </span>File structure:</span>
|
||||
<span id="cb2-19"><a href="#cb2-19" aria-hidden="true" tabindex="-1"></a></span>
|
||||
<span id="cb2-20"><a href="#cb2-20" aria-hidden="true" tabindex="-1"></a><span class="at"> > # </span><span class="dt"><</span><span class="kw">Feature</span><span class="ot"> title</span><span class="dt">></span></span>
|
||||
<span id="cb2-21"><a href="#cb2-21" aria-hidden="true" tabindex="-1"></a><span class="at"> ></span></span>
|
||||
<span id="cb2-22"><a href="#cb2-22" aria-hidden="true" tabindex="-1"></a><span class="at"> > ## 1. Problem / Motivation</span></span>
|
||||
<span id="cb2-23"><a href="#cb2-23" aria-hidden="true" tabindex="-1"></a><span class="at"> ></span></span>
|
||||
<span id="cb2-24"><a href="#cb2-24" aria-hidden="true" tabindex="-1"></a><span class="at"> > ## 2. Goals</span></span>
|
||||
<span id="cb2-25"><a href="#cb2-25" aria-hidden="true" tabindex="-1"></a><span class="at"> ></span></span>
|
||||
<span id="cb2-26"><a href="#cb2-26" aria-hidden="true" tabindex="-1"></a><span class="at"> > ## 3. Non‑Goals</span></span>
|
||||
<span id="cb2-27"><a href="#cb2-27" aria-hidden="true" tabindex="-1"></a><span class="at"> ></span></span>
|
||||
<span id="cb2-28"><a href="#cb2-28" aria-hidden="true" tabindex="-1"></a><span class="at"> > ## 4. Target Users & Personas</span></span>
|
||||
<span id="cb2-29"><a href="#cb2-29" aria-hidden="true" tabindex="-1"></a><span class="at"> ></span></span>
|
||||
<span id="cb2-30"><a href="#cb2-30" aria-hidden="true" tabindex="-1"></a><span class="at"> > ## 5. User Stories (Gherkin “Given/When/Then”)</span></span>
|
||||
<span id="cb2-31"><a href="#cb2-31" aria-hidden="true" tabindex="-1"></a><span class="at"> ></span></span>
|
||||
<span id="cb2-32"><a href="#cb2-32" aria-hidden="true" tabindex="-1"></a><span class="at"> > ## 6. Acceptance Criteria</span></span>
|
||||
<span id="cb2-33"><a href="#cb2-33" aria-hidden="true" tabindex="-1"></a><span class="at"> ></span></span>
|
||||
<span id="cb2-34"><a href="#cb2-34" aria-hidden="true" tabindex="-1"></a><span class="at"> > ## 7. Technical Notes / Dependencies</span></span>
|
||||
<span id="cb2-35"><a href="#cb2-35" aria-hidden="true" tabindex="-1"></a><span class="at"> ></span></span>
|
||||
<span id="cb2-36"><a href="#cb2-36" aria-hidden="true" tabindex="-1"></a><span class="at"> > ## 8. Open Questions</span></span>
|
||||
<span id="cb2-37"><a href="#cb2-37" aria-hidden="true" tabindex="-1"></a></span>
|
||||
<span id="cb2-38"><a href="#cb2-38" aria-hidden="true" tabindex="-1"></a><span class="fu">### Process</span></span>
|
||||
<span id="cb2-39"><a href="#cb2-39" aria-hidden="true" tabindex="-1"></a></span>
|
||||
<span id="cb2-40"><a href="#cb2-40" aria-hidden="true" tabindex="-1"></a><span class="ss">1. </span>Stakeholder provides a single‑sentence feature idea and invokes this rule.</span>
|
||||
<span id="cb2-41"><a href="#cb2-41" aria-hidden="true" tabindex="-1"></a><span class="ss">2. </span>Look at specifications in <span class="in">`specs/`</span> and inspect the code if needed to get an</span>
|
||||
<span id="cb2-42"><a href="#cb2-42" aria-hidden="true" tabindex="-1"></a> idea what the Stakeholder expects from this feature.</span>
|
||||
<span id="cb2-43"><a href="#cb2-43" aria-hidden="true" tabindex="-1"></a><span class="ss">3. </span>Ask up to five clarifying questions (Q1 … Q5). If anything is still vague</span>
|
||||
<span id="cb2-44"><a href="#cb2-44" aria-hidden="true" tabindex="-1"></a> after five, look into the project with the new information provided. You may</span>
|
||||
<span id="cb2-45"><a href="#cb2-45" aria-hidden="true" tabindex="-1"></a> ask for further clarification up to 3 times following this schema, else flag</span>
|
||||
<span id="cb2-46"><a href="#cb2-46" aria-hidden="true" tabindex="-1"></a> it in _Open Questions_.</span>
|
||||
<span id="cb2-47"><a href="#cb2-47" aria-hidden="true" tabindex="-1"></a><span class="ss">4. </span>After questions are answered reply exactly: Ready to generate the PRD.</span>
|
||||
<span id="cb2-48"><a href="#cb2-48" aria-hidden="true" tabindex="-1"></a><span class="ss">5. </span>On a user message that contains only the word "go" (case‑insensitive):</span>
|
||||
<span id="cb2-49"><a href="#cb2-49" aria-hidden="true" tabindex="-1"></a><span class="ss"> - </span>Generate /tasks/<span class="dt"><</span><span class="kw">feature</span><span class="dt">></span>/PRD.md following _Output_ spec.</span>
|
||||
<span id="cb2-50"><a href="#cb2-50" aria-hidden="true" tabindex="-1"></a><span class="ss"> - </span>Reply: <span class="dt"><</span><span class="kw">feature</span><span class="dt">></span>/PRD.md created – review it.</span>
|
||||
<span id="cb2-51"><a href="#cb2-51" aria-hidden="true" tabindex="-1"></a></span>
|
||||
<span id="cb2-52"><a href="#cb2-52" aria-hidden="true" tabindex="-1"></a><span class="ss">6. </span>STOP. Do **not** generate tasks or code in this rule.</span>
|
||||
<span id="cb2-53"><a href="#cb2-53" aria-hidden="true" tabindex="-1"></a></span>
|
||||
<span id="cb2-54"><a href="#cb2-54" aria-hidden="true" tabindex="-1"></a><span class="fu">### Writing guidelines</span></span>
|
||||
<span id="cb2-55"><a href="#cb2-55" aria-hidden="true" tabindex="-1"></a></span>
|
||||
<span id="cb2-56"><a href="#cb2-56" aria-hidden="true" tabindex="-1"></a><span class="ss">- </span>Keep each bullet ≤120 characters.</span>
|
||||
<span id="cb2-57"><a href="#cb2-57" aria-hidden="true" tabindex="-1"></a><span class="ss">- </span>Use action verbs and measurable language.</span>
|
||||
<span id="cb2-58"><a href="#cb2-58" aria-hidden="true" tabindex="-1"></a><span class="ss">- </span>Leave TBDs only in _Open Questions_.</span>
|
||||
<span id="cb2-59"><a href="#cb2-59" aria-hidden="true" tabindex="-1"></a><span class="ss">- </span>No business fluff – pretend the reader is a junior developer.</span>
|
||||
<span id="cb2-60"><a href="#cb2-60" aria-hidden="true" tabindex="-1"></a></span>
|
||||
<span id="cb2-61"><a href="#cb2-61" aria-hidden="true" tabindex="-1"></a><span class="fu">### Safety rails</span></span>
|
||||
<span id="cb2-62"><a href="#cb2-62" aria-hidden="true" tabindex="-1"></a></span>
|
||||
<span id="cb2-63"><a href="#cb2-63" aria-hidden="true" tabindex="-1"></a><span class="ss">- </span>Assume all work happens in a non‑production environment, unless otherwise</span>
|
||||
<span id="cb2-64"><a href="#cb2-64" aria-hidden="true" tabindex="-1"></a> stated or requested by you.</span>
|
||||
<span id="cb2-65"><a href="#cb2-65" aria-hidden="true" tabindex="-1"></a><span class="ss">- </span>Do not include sensitive data or credentials in the PRD.</span>
|
||||
<span id="cb2-66"><a href="#cb2-66" aria-hidden="true" tabindex="-1"></a><span class="ss">- </span>Check the generated Document with <span class="in">`markdownlint`</span> (if available), apply</span>
|
||||
<span id="cb2-67"><a href="#cb2-67" aria-hidden="true" tabindex="-1"></a> auto-fixes and fix the remaining issues manually.</span></code><button title="In die Zwischenablage kopieren" class="code-copy-button"><i class="bi"></i></button></pre></div>
|
||||
</div>
|
||||
<p>A call to this rule usually looks like <code>@generate-prd We noticed, that …. Therefore investigate the codebase to come up with a PRD addressing these issues.</code>.</p>
|
||||
</section>
|
||||
@ -907,121 +926,118 @@ This is most often the most trivial step. Everything is known and formulated for
|
||||
<span id="cb3-27"><a href="#cb3-27" aria-hidden="true" tabindex="-1"></a> <span class="in">```</span></span>
|
||||
<span id="cb3-28"><a href="#cb3-28" aria-hidden="true" tabindex="-1"></a></span>
|
||||
<span id="cb3-29"><a href="#cb3-29" aria-hidden="true" tabindex="-1"></a><span class="ss">2. </span>**Scope and Boundaries**</span>
|
||||
<span id="cb3-30"><a href="#cb3-30" aria-hidden="true" tabindex="-1"></a></span>
|
||||
<span id="cb3-31"><a href="#cb3-31" aria-hidden="true" tabindex="-1"></a><span class="ss"> - </span>What is included/excluded</span>
|
||||
<span id="cb3-32"><a href="#cb3-32" aria-hidden="true" tabindex="-1"></a><span class="ss"> - </span>Dependencies on other specifications</span>
|
||||
<span id="cb3-33"><a href="#cb3-33" aria-hidden="true" tabindex="-1"></a><span class="ss"> - </span>Relationship to other components</span>
|
||||
<span id="cb3-34"><a href="#cb3-34" aria-hidden="true" tabindex="-1"></a></span>
|
||||
<span id="cb3-35"><a href="#cb3-35" aria-hidden="true" tabindex="-1"></a><span class="ss">3. </span>**Detailed Requirements**</span>
|
||||
<span id="cb3-36"><a href="#cb3-36" aria-hidden="true" tabindex="-1"></a></span>
|
||||
<span id="cb3-37"><a href="#cb3-37" aria-hidden="true" tabindex="-1"></a><span class="ss"> - </span>Structured by logical sections</span>
|
||||
<span id="cb3-38"><a href="#cb3-38" aria-hidden="true" tabindex="-1"></a><span class="ss"> - </span>Clear, unambiguous language</span>
|
||||
<span id="cb3-39"><a href="#cb3-39" aria-hidden="true" tabindex="-1"></a><span class="ss"> - </span>Examples where helpful</span>
|
||||
<span id="cb3-40"><a href="#cb3-40" aria-hidden="true" tabindex="-1"></a></span>
|
||||
<span id="cb3-41"><a href="#cb3-41" aria-hidden="true" tabindex="-1"></a><span class="ss">4. </span>**Error Handling**</span>
|
||||
<span id="cb3-42"><a href="#cb3-42" aria-hidden="true" tabindex="-1"></a></span>
|
||||
<span id="cb3-43"><a href="#cb3-43" aria-hidden="true" tabindex="-1"></a><span class="ss"> - </span>How errors should be handled</span>
|
||||
<span id="cb3-44"><a href="#cb3-44" aria-hidden="true" tabindex="-1"></a><span class="ss"> - </span>Fallback behaviors</span>
|
||||
<span id="cb3-45"><a href="#cb3-45" aria-hidden="true" tabindex="-1"></a><span class="ss"> - </span>Edge cases</span>
|
||||
<span id="cb3-46"><a href="#cb3-46" aria-hidden="true" tabindex="-1"></a></span>
|
||||
<span id="cb3-47"><a href="#cb3-47" aria-hidden="true" tabindex="-1"></a><span class="ss">5. </span>**Testing Requirements**</span>
|
||||
<span id="cb3-48"><a href="#cb3-48" aria-hidden="true" tabindex="-1"></a><span class="ss"> - </span>Expected test coverage</span>
|
||||
<span id="cb3-49"><a href="#cb3-49" aria-hidden="true" tabindex="-1"></a><span class="ss"> - </span>Snapshot requirements</span>
|
||||
<span id="cb3-50"><a href="#cb3-50" aria-hidden="true" tabindex="-1"></a><span class="ss"> - </span>Approval test criteria</span>
|
||||
<span id="cb3-51"><a href="#cb3-51" aria-hidden="true" tabindex="-1"></a></span>
|
||||
<span id="cb3-52"><a href="#cb3-52" aria-hidden="true" tabindex="-1"></a><span class="fu">## Writing Standards</span></span>
|
||||
<span id="cb3-53"><a href="#cb3-53" aria-hidden="true" tabindex="-1"></a></span>
|
||||
<span id="cb3-54"><a href="#cb3-54" aria-hidden="true" tabindex="-1"></a><span class="fu">### Clarity and Precision</span></span>
|
||||
<span id="cb3-55"><a href="#cb3-55" aria-hidden="true" tabindex="-1"></a></span>
|
||||
<span id="cb3-56"><a href="#cb3-56" aria-hidden="true" tabindex="-1"></a><span class="ss">- </span>**Use specific language**: Avoid vague terms like "should" or "might"</span>
|
||||
<span id="cb3-57"><a href="#cb3-57" aria-hidden="true" tabindex="-1"></a><span class="ss">- </span>**Provide examples**: Include concrete examples for complex requirements</span>
|
||||
<span id="cb3-58"><a href="#cb3-58" aria-hidden="true" tabindex="-1"></a><span class="ss">- </span>**Define terms**: Clearly define any technical terms or concepts</span>
|
||||
<span id="cb3-59"><a href="#cb3-59" aria-hidden="true" tabindex="-1"></a><span class="ss">- </span>**Use consistent formatting**: Follow established patterns from existing specs</span>
|
||||
<span id="cb3-60"><a href="#cb3-60" aria-hidden="true" tabindex="-1"></a></span>
|
||||
<span id="cb3-61"><a href="#cb3-61" aria-hidden="true" tabindex="-1"></a><span class="fu">### Structure and Organization</span></span>
|
||||
<span id="cb3-62"><a href="#cb3-62" aria-hidden="true" tabindex="-1"></a></span>
|
||||
<span id="cb3-63"><a href="#cb3-63" aria-hidden="true" tabindex="-1"></a><span class="ss">- </span>**Logical flow**: Organize sections in logical order</span>
|
||||
<span id="cb3-64"><a href="#cb3-64" aria-hidden="true" tabindex="-1"></a><span class="ss">- </span>**Consistent headings**: Use consistent heading levels and naming</span>
|
||||
<span id="cb3-65"><a href="#cb3-65" aria-hidden="true" tabindex="-1"></a><span class="ss">- </span>**Cross-references**: Link to related specifications using</span>
|
||||
<span id="cb3-66"><a href="#cb3-66" aria-hidden="true" tabindex="-1"></a> <span class="in">`[spec_name](mdc:specs/spec_name.md)`</span></span>
|
||||
<span id="cb3-67"><a href="#cb3-67" aria-hidden="true" tabindex="-1"></a><span class="ss">- </span>**Code blocks**: Use appropriate language tags for code examples</span>
|
||||
<span id="cb3-68"><a href="#cb3-68" aria-hidden="true" tabindex="-1"></a></span>
|
||||
<span id="cb3-69"><a href="#cb3-69" aria-hidden="true" tabindex="-1"></a><span class="fu">### Completeness</span></span>
|
||||
<span id="cb3-70"><a href="#cb3-70" aria-hidden="true" tabindex="-1"></a></span>
|
||||
<span id="cb3-71"><a href="#cb3-71" aria-hidden="true" tabindex="-1"></a><span class="ss">- </span>**Cover all cases**: Address normal, error, and edge cases</span>
|
||||
<span id="cb3-72"><a href="#cb3-72" aria-hidden="true" tabindex="-1"></a><span class="ss">- </span>**Be exhaustive**: Don't assume implementation details</span>
|
||||
<span id="cb3-73"><a href="#cb3-73" aria-hidden="true" tabindex="-1"></a><span class="ss">- </span>**Consider interactions**: How this spec relates to others</span>
|
||||
<span id="cb3-74"><a href="#cb3-74" aria-hidden="true" tabindex="-1"></a><span class="ss">- </span>**Future-proof**: Consider potential changes and extensions</span>
|
||||
<span id="cb3-75"><a href="#cb3-75" aria-hidden="true" tabindex="-1"></a></span>
|
||||
<span id="cb3-76"><a href="#cb3-76" aria-hidden="true" tabindex="-1"></a><span class="fu">## Specification Maintenance</span></span>
|
||||
<span id="cb3-77"><a href="#cb3-77" aria-hidden="true" tabindex="-1"></a></span>
|
||||
<span id="cb3-78"><a href="#cb3-78" aria-hidden="true" tabindex="-1"></a><span class="fu">### Version Control</span></span>
|
||||
<span id="cb3-79"><a href="#cb3-79" aria-hidden="true" tabindex="-1"></a></span>
|
||||
<span id="cb3-80"><a href="#cb3-80" aria-hidden="true" tabindex="-1"></a><span class="ss">- </span>**Update specs first**: When changing behavior, update spec before</span>
|
||||
<span id="cb3-81"><a href="#cb3-81" aria-hidden="true" tabindex="-1"></a> implementation</span>
|
||||
<span id="cb3-82"><a href="#cb3-82" aria-hidden="true" tabindex="-1"></a><span class="ss">- </span>**Document changes**: Use clear commit messages explaining spec changes</span>
|
||||
<span id="cb3-83"><a href="#cb3-83" aria-hidden="true" tabindex="-1"></a><span class="ss">- </span>**Review process**: Have specs reviewed before implementation</span>
|
||||
<span id="cb3-84"><a href="#cb3-84" aria-hidden="true" tabindex="-1"></a></span>
|
||||
<span id="cb3-85"><a href="#cb3-85" aria-hidden="true" tabindex="-1"></a><span class="fu">### Consistency Checks</span></span>
|
||||
<span id="cb3-86"><a href="#cb3-86" aria-hidden="true" tabindex="-1"></a></span>
|
||||
<span id="cb3-87"><a href="#cb3-87" aria-hidden="true" tabindex="-1"></a><span class="ss">- </span>**Cross-reference validation**: Ensure all links to other specs are valid</span>
|
||||
<span id="cb3-88"><a href="#cb3-88" aria-hidden="true" tabindex="-1"></a><span class="ss">- </span>**Terminology consistency**: Use consistent terms across all specs</span>
|
||||
<span id="cb3-89"><a href="#cb3-89" aria-hidden="true" tabindex="-1"></a><span class="ss">- </span>**Format consistency**: Follow established formatting patterns</span>
|
||||
<span id="cb3-90"><a href="#cb3-90" aria-hidden="true" tabindex="-1"></a></span>
|
||||
<span id="cb3-91"><a href="#cb3-91" aria-hidden="true" tabindex="-1"></a><span class="fu">### Testing Integration</span></span>
|
||||
<span id="cb3-92"><a href="#cb3-92" aria-hidden="true" tabindex="-1"></a></span>
|
||||
<span id="cb3-93"><a href="#cb3-93" aria-hidden="true" tabindex="-1"></a><span class="ss">- </span>**Spec-driven tests**: Write tests based on specification requirements</span>
|
||||
<span id="cb3-94"><a href="#cb3-94" aria-hidden="true" tabindex="-1"></a><span class="ss">- </span>**Snapshot validation**: Ensure snapshots match specification exactly</span>
|
||||
<span id="cb3-95"><a href="#cb3-95" aria-hidden="true" tabindex="-1"></a><span class="ss">- </span>**Approval tests**: Use approval tests to catch spec violations</span>
|
||||
<span id="cb3-96"><a href="#cb3-96" aria-hidden="true" tabindex="-1"></a></span>
|
||||
<span id="cb3-97"><a href="#cb3-97" aria-hidden="true" tabindex="-1"></a><span class="fu">## Quality Checklist</span></span>
|
||||
<span id="cb3-98"><a href="#cb3-98" aria-hidden="true" tabindex="-1"></a></span>
|
||||
<span id="cb3-99"><a href="#cb3-99" aria-hidden="true" tabindex="-1"></a><span class="fu">### Before Finalizing Specification</span></span>
|
||||
<span id="cb3-100"><a href="#cb3-100" aria-hidden="true" tabindex="-1"></a></span>
|
||||
<span id="cb3-101"><a href="#cb3-101" aria-hidden="true" tabindex="-1"></a><span class="ss">- </span><span class="va">[ ]</span> All requirements clearly stated</span>
|
||||
<span id="cb3-102"><a href="#cb3-102" aria-hidden="true" tabindex="-1"></a><span class="ss">- </span><span class="va">[ ]</span> Examples provided for complex requirements</span>
|
||||
<span id="cb3-103"><a href="#cb3-103" aria-hidden="true" tabindex="-1"></a><span class="ss">- </span><span class="va">[ ]</span> Error cases covered</span>
|
||||
<span id="cb3-104"><a href="#cb3-104" aria-hidden="true" tabindex="-1"></a><span class="ss">- </span><span class="va">[ ]</span> Cross-references to other specs included</span>
|
||||
<span id="cb3-105"><a href="#cb3-105" aria-hidden="true" tabindex="-1"></a><span class="ss">- </span><span class="va">[ ]</span> Out of scope items clearly defined</span>
|
||||
<span id="cb3-106"><a href="#cb3-106" aria-hidden="true" tabindex="-1"></a><span class="ss">- </span><span class="va">[ ]</span> Testing requirements specified</span>
|
||||
<span id="cb3-107"><a href="#cb3-107" aria-hidden="true" tabindex="-1"></a><span class="ss">- </span><span class="va">[ ]</span> Consistent formatting throughout</span>
|
||||
<span id="cb3-108"><a href="#cb3-108" aria-hidden="true" tabindex="-1"></a><span class="ss">- </span><span class="va">[ ]</span> Check the generated Document with <span class="in">`markdownlint`</span> (if available), apply</span>
|
||||
<span id="cb3-109"><a href="#cb3-109" aria-hidden="true" tabindex="-1"></a> auto-fixes and fix the remaining issues manually.</span>
|
||||
<span id="cb3-110"><a href="#cb3-110" aria-hidden="true" tabindex="-1"></a></span>
|
||||
<span id="cb3-111"><a href="#cb3-111" aria-hidden="true" tabindex="-1"></a><span class="fu">### Review Criteria</span></span>
|
||||
<span id="cb3-112"><a href="#cb3-112" aria-hidden="true" tabindex="-1"></a></span>
|
||||
<span id="cb3-113"><a href="#cb3-113" aria-hidden="true" tabindex="-1"></a><span class="ss">- </span><span class="va">[ ]</span> Is the specification unambiguous?</span>
|
||||
<span id="cb3-114"><a href="#cb3-114" aria-hidden="true" tabindex="-1"></a><span class="ss">- </span><span class="va">[ ]</span> Are all edge cases covered?</span>
|
||||
<span id="cb3-115"><a href="#cb3-115" aria-hidden="true" tabindex="-1"></a><span class="ss">- </span><span class="va">[ ]</span> Does it integrate well with other specs?</span>
|
||||
<span id="cb3-116"><a href="#cb3-116" aria-hidden="true" tabindex="-1"></a><span class="ss">- </span><span class="va">[ ]</span> Is it testable?</span>
|
||||
<span id="cb3-117"><a href="#cb3-117" aria-hidden="true" tabindex="-1"></a><span class="ss">- </span><span class="va">[ ]</span> Is it maintainable?</span>
|
||||
<span id="cb3-118"><a href="#cb3-118" aria-hidden="true" tabindex="-1"></a></span>
|
||||
<span id="cb3-119"><a href="#cb3-119" aria-hidden="true" tabindex="-1"></a><span class="fu">## Common Pitfalls to Avoid</span></span>
|
||||
<span id="cb3-120"><a href="#cb3-120" aria-hidden="true" tabindex="-1"></a></span>
|
||||
<span id="cb3-121"><a href="#cb3-121" aria-hidden="true" tabindex="-1"></a><span class="fu">### Ambiguity</span></span>
|
||||
<span id="cb3-122"><a href="#cb3-122" aria-hidden="true" tabindex="-1"></a></span>
|
||||
<span id="cb3-123"><a href="#cb3-123" aria-hidden="true" tabindex="-1"></a><span class="ss">- </span>**Vague language**: "The system should handle errors gracefully"</span>
|
||||
<span id="cb3-124"><a href="#cb3-124" aria-hidden="true" tabindex="-1"></a><span class="ss">- </span>**Missing details**: Not specifying exact error handling behavior</span>
|
||||
<span id="cb3-125"><a href="#cb3-125" aria-hidden="true" tabindex="-1"></a><span class="ss">- </span>**Unclear relationships**: Not explaining how components interact</span>
|
||||
<span id="cb3-126"><a href="#cb3-126" aria-hidden="true" tabindex="-1"></a></span>
|
||||
<span id="cb3-127"><a href="#cb3-127" aria-hidden="true" tabindex="-1"></a><span class="fu">### Inconsistency</span></span>
|
||||
<span id="cb3-128"><a href="#cb3-128" aria-hidden="true" tabindex="-1"></a></span>
|
||||
<span id="cb3-129"><a href="#cb3-129" aria-hidden="true" tabindex="-1"></a><span class="ss">- </span>**Different terms**: Using different terms for the same concept</span>
|
||||
<span id="cb3-130"><a href="#cb3-130" aria-hidden="true" tabindex="-1"></a><span class="ss">- </span>**Inconsistent formatting**: Not following established patterns</span>
|
||||
<span id="cb3-131"><a href="#cb3-131" aria-hidden="true" tabindex="-1"></a><span class="ss">- </span>**Conflicting requirements**: Requirements that contradict other specs</span>
|
||||
<span id="cb3-132"><a href="#cb3-132" aria-hidden="true" tabindex="-1"></a></span>
|
||||
<span id="cb3-133"><a href="#cb3-133" aria-hidden="true" tabindex="-1"></a><span class="fu">### Incompleteness</span></span>
|
||||
<span id="cb3-134"><a href="#cb3-134" aria-hidden="true" tabindex="-1"></a></span>
|
||||
<span id="cb3-135"><a href="#cb3-135" aria-hidden="true" tabindex="-1"></a><span class="ss">- </span>**Missing edge cases**: Not considering unusual scenarios</span>
|
||||
<span id="cb3-136"><a href="#cb3-136" aria-hidden="true" tabindex="-1"></a><span class="ss">- </span>**Incomplete examples**: Examples that don't cover all cases</span>
|
||||
<span id="cb3-137"><a href="#cb3-137" aria-hidden="true" tabindex="-1"></a><span class="ss">- </span>**Missing error handling**: Not specifying what happens when things go wrong</span>
|
||||
<span id="cb3-138"><a href="#cb3-138" aria-hidden="true" tabindex="-1"></a></span>
|
||||
<span id="cb3-139"><a href="#cb3-139" aria-hidden="true" tabindex="-1"></a><span class="fu">## Related Rules</span></span>
|
||||
<span id="cb3-140"><a href="#cb3-140" aria-hidden="true" tabindex="-1"></a></span>
|
||||
<span id="cb3-141"><a href="#cb3-141" aria-hidden="true" tabindex="-1"></a><span class="ss">- </span><span class="co">[</span><span class="ot">spec-compliance-investigation.mdc</span><span class="co">](mdc:.cursor/rules/spec-compliance-investigation.mdc)</span></span>
|
||||
<span id="cb3-142"><a href="#cb3-142" aria-hidden="true" tabindex="-1"></a> How to investigate spec-implementation discrepancies</span>
|
||||
<span id="cb3-143"><a href="#cb3-143" aria-hidden="true" tabindex="-1"></a><span class="ss">- </span><span class="co">[</span><span class="ot">base_overview.mdc</span><span class="co">](mdc:.cursor/rules/base_overview.mdc)</span> Project structure and</span>
|
||||
<span id="cb3-144"><a href="#cb3-144" aria-hidden="true" tabindex="-1"></a> conventions</span></code><button title="In die Zwischenablage kopieren" class="code-copy-button"><i class="bi"></i></button></pre></div>
|
||||
<span id="cb3-30"><a href="#cb3-30" aria-hidden="true" tabindex="-1"></a><span class="ss"> - </span>What is included/excluded</span>
|
||||
<span id="cb3-31"><a href="#cb3-31" aria-hidden="true" tabindex="-1"></a><span class="ss"> - </span>Dependencies on other specifications</span>
|
||||
<span id="cb3-32"><a href="#cb3-32" aria-hidden="true" tabindex="-1"></a><span class="ss"> - </span>Relationship to other components</span>
|
||||
<span id="cb3-33"><a href="#cb3-33" aria-hidden="true" tabindex="-1"></a></span>
|
||||
<span id="cb3-34"><a href="#cb3-34" aria-hidden="true" tabindex="-1"></a><span class="ss">3. </span>**Detailed Requirements**</span>
|
||||
<span id="cb3-35"><a href="#cb3-35" aria-hidden="true" tabindex="-1"></a><span class="ss"> - </span>Structured by logical sections</span>
|
||||
<span id="cb3-36"><a href="#cb3-36" aria-hidden="true" tabindex="-1"></a><span class="ss"> - </span>Clear, unambiguous language</span>
|
||||
<span id="cb3-37"><a href="#cb3-37" aria-hidden="true" tabindex="-1"></a><span class="ss"> - </span>Examples where helpful</span>
|
||||
<span id="cb3-38"><a href="#cb3-38" aria-hidden="true" tabindex="-1"></a></span>
|
||||
<span id="cb3-39"><a href="#cb3-39" aria-hidden="true" tabindex="-1"></a><span class="ss">4. </span>**Error Handling**</span>
|
||||
<span id="cb3-40"><a href="#cb3-40" aria-hidden="true" tabindex="-1"></a><span class="ss"> - </span>How errors should be handled</span>
|
||||
<span id="cb3-41"><a href="#cb3-41" aria-hidden="true" tabindex="-1"></a><span class="ss"> - </span>Fallback behaviors</span>
|
||||
<span id="cb3-42"><a href="#cb3-42" aria-hidden="true" tabindex="-1"></a><span class="ss"> - </span>Edge cases</span>
|
||||
<span id="cb3-43"><a href="#cb3-43" aria-hidden="true" tabindex="-1"></a></span>
|
||||
<span id="cb3-44"><a href="#cb3-44" aria-hidden="true" tabindex="-1"></a><span class="ss">5. </span>**Testing Requirements**</span>
|
||||
<span id="cb3-45"><a href="#cb3-45" aria-hidden="true" tabindex="-1"></a><span class="ss"> - </span>Expected test coverage</span>
|
||||
<span id="cb3-46"><a href="#cb3-46" aria-hidden="true" tabindex="-1"></a><span class="ss"> - </span>Snapshot requirements</span>
|
||||
<span id="cb3-47"><a href="#cb3-47" aria-hidden="true" tabindex="-1"></a><span class="ss"> - </span>Approval test criteria</span>
|
||||
<span id="cb3-48"><a href="#cb3-48" aria-hidden="true" tabindex="-1"></a></span>
|
||||
<span id="cb3-49"><a href="#cb3-49" aria-hidden="true" tabindex="-1"></a><span class="fu">## Writing Standards</span></span>
|
||||
<span id="cb3-50"><a href="#cb3-50" aria-hidden="true" tabindex="-1"></a></span>
|
||||
<span id="cb3-51"><a href="#cb3-51" aria-hidden="true" tabindex="-1"></a><span class="fu">### Clarity and Precision</span></span>
|
||||
<span id="cb3-52"><a href="#cb3-52" aria-hidden="true" tabindex="-1"></a></span>
|
||||
<span id="cb3-53"><a href="#cb3-53" aria-hidden="true" tabindex="-1"></a><span class="ss">- </span>**Use specific language**: Avoid vague terms like "should" or "might"</span>
|
||||
<span id="cb3-54"><a href="#cb3-54" aria-hidden="true" tabindex="-1"></a><span class="ss">- </span>**Provide examples**: Include concrete examples for complex requirements</span>
|
||||
<span id="cb3-55"><a href="#cb3-55" aria-hidden="true" tabindex="-1"></a><span class="ss">- </span>**Define terms**: Clearly define any technical terms or concepts</span>
|
||||
<span id="cb3-56"><a href="#cb3-56" aria-hidden="true" tabindex="-1"></a><span class="ss">- </span>**Use consistent formatting**: Follow established patterns from existing specs</span>
|
||||
<span id="cb3-57"><a href="#cb3-57" aria-hidden="true" tabindex="-1"></a></span>
|
||||
<span id="cb3-58"><a href="#cb3-58" aria-hidden="true" tabindex="-1"></a><span class="fu">### Structure and Organization</span></span>
|
||||
<span id="cb3-59"><a href="#cb3-59" aria-hidden="true" tabindex="-1"></a></span>
|
||||
<span id="cb3-60"><a href="#cb3-60" aria-hidden="true" tabindex="-1"></a><span class="ss">- </span>**Logical flow**: Organize sections in logical order</span>
|
||||
<span id="cb3-61"><a href="#cb3-61" aria-hidden="true" tabindex="-1"></a><span class="ss">- </span>**Consistent headings**: Use consistent heading levels and naming</span>
|
||||
<span id="cb3-62"><a href="#cb3-62" aria-hidden="true" tabindex="-1"></a><span class="ss">- </span>**Cross-references**: Link to related specifications using</span>
|
||||
<span id="cb3-63"><a href="#cb3-63" aria-hidden="true" tabindex="-1"></a> <span class="in">`[spec_name](mdc:specs/spec_name.md)`</span></span>
|
||||
<span id="cb3-64"><a href="#cb3-64" aria-hidden="true" tabindex="-1"></a><span class="ss">- </span>**Code blocks**: Use appropriate language tags for code examples</span>
|
||||
<span id="cb3-65"><a href="#cb3-65" aria-hidden="true" tabindex="-1"></a></span>
|
||||
<span id="cb3-66"><a href="#cb3-66" aria-hidden="true" tabindex="-1"></a><span class="fu">### Completeness</span></span>
|
||||
<span id="cb3-67"><a href="#cb3-67" aria-hidden="true" tabindex="-1"></a></span>
|
||||
<span id="cb3-68"><a href="#cb3-68" aria-hidden="true" tabindex="-1"></a><span class="ss">- </span>**Cover all cases**: Address normal, error, and edge cases</span>
|
||||
<span id="cb3-69"><a href="#cb3-69" aria-hidden="true" tabindex="-1"></a><span class="ss">- </span>**Be exhaustive**: Don't assume implementation details</span>
|
||||
<span id="cb3-70"><a href="#cb3-70" aria-hidden="true" tabindex="-1"></a><span class="ss">- </span>**Consider interactions**: How this spec relates to others</span>
|
||||
<span id="cb3-71"><a href="#cb3-71" aria-hidden="true" tabindex="-1"></a><span class="ss">- </span>**Future-proof**: Consider potential changes and extensions</span>
|
||||
<span id="cb3-72"><a href="#cb3-72" aria-hidden="true" tabindex="-1"></a></span>
|
||||
<span id="cb3-73"><a href="#cb3-73" aria-hidden="true" tabindex="-1"></a><span class="fu">## Specification Maintenance</span></span>
|
||||
<span id="cb3-74"><a href="#cb3-74" aria-hidden="true" tabindex="-1"></a></span>
|
||||
<span id="cb3-75"><a href="#cb3-75" aria-hidden="true" tabindex="-1"></a><span class="fu">### Version Control</span></span>
|
||||
<span id="cb3-76"><a href="#cb3-76" aria-hidden="true" tabindex="-1"></a></span>
|
||||
<span id="cb3-77"><a href="#cb3-77" aria-hidden="true" tabindex="-1"></a><span class="ss">- </span>**Update specs first**: When changing behavior, update spec before</span>
|
||||
<span id="cb3-78"><a href="#cb3-78" aria-hidden="true" tabindex="-1"></a> implementation</span>
|
||||
<span id="cb3-79"><a href="#cb3-79" aria-hidden="true" tabindex="-1"></a><span class="ss">- </span>**Document changes**: Use clear commit messages explaining spec changes</span>
|
||||
<span id="cb3-80"><a href="#cb3-80" aria-hidden="true" tabindex="-1"></a><span class="ss">- </span>**Review process**: Have specs reviewed before implementation</span>
|
||||
<span id="cb3-81"><a href="#cb3-81" aria-hidden="true" tabindex="-1"></a></span>
|
||||
<span id="cb3-82"><a href="#cb3-82" aria-hidden="true" tabindex="-1"></a><span class="fu">### Consistency Checks</span></span>
|
||||
<span id="cb3-83"><a href="#cb3-83" aria-hidden="true" tabindex="-1"></a></span>
|
||||
<span id="cb3-84"><a href="#cb3-84" aria-hidden="true" tabindex="-1"></a><span class="ss">- </span>**Cross-reference validation**: Ensure all links to other specs are valid</span>
|
||||
<span id="cb3-85"><a href="#cb3-85" aria-hidden="true" tabindex="-1"></a><span class="ss">- </span>**Terminology consistency**: Use consistent terms across all specs</span>
|
||||
<span id="cb3-86"><a href="#cb3-86" aria-hidden="true" tabindex="-1"></a><span class="ss">- </span>**Format consistency**: Follow established formatting patterns</span>
|
||||
<span id="cb3-87"><a href="#cb3-87" aria-hidden="true" tabindex="-1"></a></span>
|
||||
<span id="cb3-88"><a href="#cb3-88" aria-hidden="true" tabindex="-1"></a><span class="fu">### Testing Integration</span></span>
|
||||
<span id="cb3-89"><a href="#cb3-89" aria-hidden="true" tabindex="-1"></a></span>
|
||||
<span id="cb3-90"><a href="#cb3-90" aria-hidden="true" tabindex="-1"></a><span class="ss">- </span>**Spec-driven tests**: Write tests based on specification requirements</span>
|
||||
<span id="cb3-91"><a href="#cb3-91" aria-hidden="true" tabindex="-1"></a><span class="ss">- </span>**Snapshot validation**: Ensure snapshots match specification exactly</span>
|
||||
<span id="cb3-92"><a href="#cb3-92" aria-hidden="true" tabindex="-1"></a><span class="ss">- </span>**Approval tests**: Use approval tests to catch spec violations</span>
|
||||
<span id="cb3-93"><a href="#cb3-93" aria-hidden="true" tabindex="-1"></a></span>
|
||||
<span id="cb3-94"><a href="#cb3-94" aria-hidden="true" tabindex="-1"></a><span class="fu">## Quality Checklist</span></span>
|
||||
<span id="cb3-95"><a href="#cb3-95" aria-hidden="true" tabindex="-1"></a></span>
|
||||
<span id="cb3-96"><a href="#cb3-96" aria-hidden="true" tabindex="-1"></a><span class="fu">### Before Finalizing Specification</span></span>
|
||||
<span id="cb3-97"><a href="#cb3-97" aria-hidden="true" tabindex="-1"></a></span>
|
||||
<span id="cb3-98"><a href="#cb3-98" aria-hidden="true" tabindex="-1"></a><span class="ss">- </span><span class="va">[ ]</span> All requirements clearly stated</span>
|
||||
<span id="cb3-99"><a href="#cb3-99" aria-hidden="true" tabindex="-1"></a><span class="ss">- </span><span class="va">[ ]</span> Examples provided for complex requirements</span>
|
||||
<span id="cb3-100"><a href="#cb3-100" aria-hidden="true" tabindex="-1"></a><span class="ss">- </span><span class="va">[ ]</span> Error cases covered</span>
|
||||
<span id="cb3-101"><a href="#cb3-101" aria-hidden="true" tabindex="-1"></a><span class="ss">- </span><span class="va">[ ]</span> Cross-references to other specs included</span>
|
||||
<span id="cb3-102"><a href="#cb3-102" aria-hidden="true" tabindex="-1"></a><span class="ss">- </span><span class="va">[ ]</span> Out of scope items clearly defined</span>
|
||||
<span id="cb3-103"><a href="#cb3-103" aria-hidden="true" tabindex="-1"></a><span class="ss">- </span><span class="va">[ ]</span> Testing requirements specified</span>
|
||||
<span id="cb3-104"><a href="#cb3-104" aria-hidden="true" tabindex="-1"></a><span class="ss">- </span><span class="va">[ ]</span> Consistent formatting throughout</span>
|
||||
<span id="cb3-105"><a href="#cb3-105" aria-hidden="true" tabindex="-1"></a><span class="ss">- </span><span class="va">[ ]</span> Check the generated Document with <span class="in">`markdownlint`</span> (if available), apply</span>
|
||||
<span id="cb3-106"><a href="#cb3-106" aria-hidden="true" tabindex="-1"></a> auto-fixes and fix the remaining issues manually.</span>
|
||||
<span id="cb3-107"><a href="#cb3-107" aria-hidden="true" tabindex="-1"></a></span>
|
||||
<span id="cb3-108"><a href="#cb3-108" aria-hidden="true" tabindex="-1"></a><span class="fu">### Review Criteria</span></span>
|
||||
<span id="cb3-109"><a href="#cb3-109" aria-hidden="true" tabindex="-1"></a></span>
|
||||
<span id="cb3-110"><a href="#cb3-110" aria-hidden="true" tabindex="-1"></a><span class="ss">- </span><span class="va">[ ]</span> Is the specification unambiguous?</span>
|
||||
<span id="cb3-111"><a href="#cb3-111" aria-hidden="true" tabindex="-1"></a><span class="ss">- </span><span class="va">[ ]</span> Are all edge cases covered?</span>
|
||||
<span id="cb3-112"><a href="#cb3-112" aria-hidden="true" tabindex="-1"></a><span class="ss">- </span><span class="va">[ ]</span> Does it integrate well with other specs?</span>
|
||||
<span id="cb3-113"><a href="#cb3-113" aria-hidden="true" tabindex="-1"></a><span class="ss">- </span><span class="va">[ ]</span> Is it testable?</span>
|
||||
<span id="cb3-114"><a href="#cb3-114" aria-hidden="true" tabindex="-1"></a><span class="ss">- </span><span class="va">[ ]</span> Is it maintainable?</span>
|
||||
<span id="cb3-115"><a href="#cb3-115" aria-hidden="true" tabindex="-1"></a></span>
|
||||
<span id="cb3-116"><a href="#cb3-116" aria-hidden="true" tabindex="-1"></a><span class="fu">## Common Pitfalls to Avoid</span></span>
|
||||
<span id="cb3-117"><a href="#cb3-117" aria-hidden="true" tabindex="-1"></a></span>
|
||||
<span id="cb3-118"><a href="#cb3-118" aria-hidden="true" tabindex="-1"></a><span class="fu">### Ambiguity</span></span>
|
||||
<span id="cb3-119"><a href="#cb3-119" aria-hidden="true" tabindex="-1"></a></span>
|
||||
<span id="cb3-120"><a href="#cb3-120" aria-hidden="true" tabindex="-1"></a><span class="ss">- </span>**Vague language**: "The system should handle errors gracefully"</span>
|
||||
<span id="cb3-121"><a href="#cb3-121" aria-hidden="true" tabindex="-1"></a><span class="ss">- </span>**Missing details**: Not specifying exact error handling behavior</span>
|
||||
<span id="cb3-122"><a href="#cb3-122" aria-hidden="true" tabindex="-1"></a><span class="ss">- </span>**Unclear relationships**: Not explaining how components interact</span>
|
||||
<span id="cb3-123"><a href="#cb3-123" aria-hidden="true" tabindex="-1"></a></span>
|
||||
<span id="cb3-124"><a href="#cb3-124" aria-hidden="true" tabindex="-1"></a><span class="fu">### Inconsistency</span></span>
|
||||
<span id="cb3-125"><a href="#cb3-125" aria-hidden="true" tabindex="-1"></a></span>
|
||||
<span id="cb3-126"><a href="#cb3-126" aria-hidden="true" tabindex="-1"></a><span class="ss">- </span>**Different terms**: Using different terms for the same concept</span>
|
||||
<span id="cb3-127"><a href="#cb3-127" aria-hidden="true" tabindex="-1"></a><span class="ss">- </span>**Inconsistent formatting**: Not following established patterns</span>
|
||||
<span id="cb3-128"><a href="#cb3-128" aria-hidden="true" tabindex="-1"></a><span class="ss">- </span>**Conflicting requirements**: Requirements that contradict other specs</span>
|
||||
<span id="cb3-129"><a href="#cb3-129" aria-hidden="true" tabindex="-1"></a></span>
|
||||
<span id="cb3-130"><a href="#cb3-130" aria-hidden="true" tabindex="-1"></a><span class="fu">### Incompleteness</span></span>
|
||||
<span id="cb3-131"><a href="#cb3-131" aria-hidden="true" tabindex="-1"></a></span>
|
||||
<span id="cb3-132"><a href="#cb3-132" aria-hidden="true" tabindex="-1"></a><span class="ss">- </span>**Missing edge cases**: Not considering unusual scenarios</span>
|
||||
<span id="cb3-133"><a href="#cb3-133" aria-hidden="true" tabindex="-1"></a><span class="ss">- </span>**Incomplete examples**: Examples that don't cover all cases</span>
|
||||
<span id="cb3-134"><a href="#cb3-134" aria-hidden="true" tabindex="-1"></a><span class="ss">- </span>**Missing error handling**: Not specifying what happens when things go wrong</span>
|
||||
<span id="cb3-135"><a href="#cb3-135" aria-hidden="true" tabindex="-1"></a></span>
|
||||
<span id="cb3-136"><a href="#cb3-136" aria-hidden="true" tabindex="-1"></a><span class="fu">## Related Rules</span></span>
|
||||
<span id="cb3-137"><a href="#cb3-137" aria-hidden="true" tabindex="-1"></a></span>
|
||||
<span id="cb3-138"><a href="#cb3-138" aria-hidden="true" tabindex="-1"></a><span class="ss">- </span><span class="co">[</span><span class="ot">spec-compliance-investigation.mdc</span><span class="co">](mdc:.cursor/rules/spec-compliance-investigation.mdc)</span></span>
|
||||
<span id="cb3-139"><a href="#cb3-139" aria-hidden="true" tabindex="-1"></a> How to investigate spec-implementation discrepancies</span>
|
||||
<span id="cb3-140"><a href="#cb3-140" aria-hidden="true" tabindex="-1"></a><span class="ss">- </span><span class="co">[</span><span class="ot">base_overview.mdc</span><span class="co">](mdc:.cursor/rules/base_overview.mdc)</span> Project structure and</span>
|
||||
<span id="cb3-141"><a href="#cb3-141" aria-hidden="true" tabindex="-1"></a> conventions</span></code><button title="In die Zwischenablage kopieren" class="code-copy-button"><i class="bi"></i></button></pre></div>
|
||||
</div>
|
||||
<p>As it is obvious this is a very intricate rule with many criteria. For this you really <strong>need</strong> a reasoning and deep-thinking model that can also reason for extended times (many minutes are normal!) and call tools every now and then to get even more information. Models like <code>o3</code>, <code>deepseek-r1</code> and the <code>opus</code>-series of <code>claude</code> really shine here.</p>
|
||||
</section>
|
||||
@ -1201,50 +1217,53 @@ This is most often the most trivial step. Everything is known and formulated for
|
||||
<span id="cb5-13"><a href="#cb5-13" aria-hidden="true" tabindex="-1"></a></span>
|
||||
<span id="cb5-14"><a href="#cb5-14" aria-hidden="true" tabindex="-1"></a><span class="fu">### Output</span></span>
|
||||
<span id="cb5-15"><a href="#cb5-15" aria-hidden="true" tabindex="-1"></a></span>
|
||||
<span id="cb5-16"><a href="#cb5-16" aria-hidden="true" tabindex="-1"></a>• Create /tasks/<span class="dt"><</span><span class="kw">feature</span><span class="dt">></span>/TASKS.md (overwrite if it exists). • Markdown only, no</span>
|
||||
<span id="cb5-17"><a href="#cb5-17" aria-hidden="true" tabindex="-1"></a>prose around it. • Epics = H2 headings (<span class="in">`## 1. <Epic>`</span>). • Tasks = unchecked</span>
|
||||
<span id="cb5-18"><a href="#cb5-18" aria-hidden="true" tabindex="-1"></a>check‑boxes (<span class="in">`- [ ] 1.1 <task>`</span>). • Sub‑tasks = indent one space under their</span>
|
||||
<span id="cb5-19"><a href="#cb5-19" aria-hidden="true" tabindex="-1"></a>parent (<span class="in">` - [ ] 1.1.1 <subtask>`</span>). • Create a</span>
|
||||
<span id="cb5-20"><a href="#cb5-20" aria-hidden="true" tabindex="-1"></a>/tasks/<span class="dt"><</span><span class="kw">feature</span><span class="dt">></span>/Task*<Epic>*<span class="dt"><</span><span class="kw">task</span><span class="dt">></span><span class="sc">\_</span><span class="dt"><</span><span class="kw">subtask</span><span class="dt">></span>.md (i.e. <span class="in">`Task_3_2_4.md`</span> for Epic</span>
|
||||
<span id="cb5-21"><a href="#cb5-21" aria-hidden="true" tabindex="-1"></a>3, Task 2, Subtask 4)</span>
|
||||
<span id="cb5-22"><a href="#cb5-22" aria-hidden="true" tabindex="-1"></a></span>
|
||||
<span id="cb5-23"><a href="#cb5-23" aria-hidden="true" tabindex="-1"></a><span class="fu">### Process</span></span>
|
||||
<span id="cb5-24"><a href="#cb5-24" aria-hidden="true" tabindex="-1"></a></span>
|
||||
<span id="cb5-25"><a href="#cb5-25" aria-hidden="true" tabindex="-1"></a><span class="ss">1. </span>Read the tagged PRD.</span>
|
||||
<span id="cb5-26"><a href="#cb5-26" aria-hidden="true" tabindex="-1"></a><span class="ss">2. </span>**Investigate** the current state of the repository to collect answers to</span>
|
||||
<span id="cb5-27"><a href="#cb5-27" aria-hidden="true" tabindex="-1"></a> your first questions. All specs for fixed behaviours and outputs are located</span>
|
||||
<span id="cb5-28"><a href="#cb5-28" aria-hidden="true" tabindex="-1"></a> in <span class="in">`specs/`</span>. **Consult those** as a source first before trying to</span>
|
||||
<span id="cb5-29"><a href="#cb5-29" aria-hidden="true" tabindex="-1"></a> reverse-engineer from the code. </span>
|
||||
<span id="cb5-30"><a href="#cb5-30" aria-hidden="true" tabindex="-1"></a> If specs are in need of change then this is also a task to be generated.</span>
|
||||
<span id="cb5-31"><a href="#cb5-31" aria-hidden="true" tabindex="-1"></a><span class="ss">3. </span>If critical info is missing and cannot be answered by looking at the code,</span>
|
||||
<span id="cb5-32"><a href="#cb5-32" aria-hidden="true" tabindex="-1"></a> ask max five clarifying questions (Q1 … Q5) and stop until answered.</span>
|
||||
<span id="cb5-33"><a href="#cb5-33" aria-hidden="true" tabindex="-1"></a><span class="ss">4. </span>After questions are answered think about the answers and: Either: look at the</span>
|
||||
<span id="cb5-34"><a href="#cb5-34" aria-hidden="true" tabindex="-1"></a> code again, then goto 3., and ask for further clarification Or: Reply</span>
|
||||
<span id="cb5-35"><a href="#cb5-35" aria-hidden="true" tabindex="-1"></a> exactly: Ready to generate the subtasks – respond **go** to proceed.</span>
|
||||
<span id="cb5-36"><a href="#cb5-36" aria-hidden="true" tabindex="-1"></a><span class="ss">5. </span>On a user message that contains only the word "go" (case‑insensitive): a.</span>
|
||||
<span id="cb5-37"><a href="#cb5-37" aria-hidden="true" tabindex="-1"></a> Generate /tasks/<span class="dt"><</span><span class="kw">feature</span><span class="dt">></span>/TASKS.md following _Output_ spec. b. Reply with:</span>
|
||||
<span id="cb5-38"><a href="#cb5-38" aria-hidden="true" tabindex="-1"></a> TASKS.md created – review them.</span>
|
||||
<span id="cb5-39"><a href="#cb5-39" aria-hidden="true" tabindex="-1"></a><span class="ss">6. </span>After TASKS.md was reviewed, create <span class="in">`Task_<e>_<t>_<s>.md`</span> for each task and</span>
|
||||
<span id="cb5-40"><a href="#cb5-40" aria-hidden="true" tabindex="-1"></a> subtask containing implementation hints like relevant specs (link them!),</span>
|
||||
<span id="cb5-41"><a href="#cb5-41" aria-hidden="true" tabindex="-1"></a> primary files to edit/review for this task, tests needing change, etc.</span>
|
||||
<span id="cb5-42"><a href="#cb5-42" aria-hidden="true" tabindex="-1"></a><span class="ss">7. </span>Stop. Do **not** begin executing tasks in this rule.</span>
|
||||
<span id="cb5-43"><a href="#cb5-43" aria-hidden="true" tabindex="-1"></a></span>
|
||||
<span id="cb5-44"><a href="#cb5-44" aria-hidden="true" tabindex="-1"></a><span class="fu">### Writing guidelines</span></span>
|
||||
<span id="cb5-45"><a href="#cb5-45" aria-hidden="true" tabindex="-1"></a></span>
|
||||
<span id="cb5-46"><a href="#cb5-46" aria-hidden="true" tabindex="-1"></a>• Each item ≤120 characters, start with an action verb. • Hints are allowed</span>
|
||||
<span id="cb5-47"><a href="#cb5-47" aria-hidden="true" tabindex="-1"></a>below each item as HTML-Comment and do not count against the 120 characters. •</span>
|
||||
<span id="cb5-48"><a href="#cb5-48" aria-hidden="true" tabindex="-1"></a>Group related work into logical epics with ≤7 direct child items. • Prefer</span>
|
||||
<span id="cb5-49"><a href="#cb5-49" aria-hidden="true" tabindex="-1"></a>concrete file paths, commands, specs or APIs when available. • Skip</span>
|
||||
<span id="cb5-50"><a href="#cb5-50" aria-hidden="true" tabindex="-1"></a>implementation details obvious from the codebase in the overview. • If a task</span>
|
||||
<span id="cb5-51"><a href="#cb5-51" aria-hidden="true" tabindex="-1"></a>only concerns up to 5 files, name them in the detailed file. Otherwise give</span>
|
||||
<span id="cb5-52"><a href="#cb5-52" aria-hidden="true" tabindex="-1"></a>hints on how to search for them (i.e. "everything under src/models/").</span>
|
||||
<span id="cb5-53"><a href="#cb5-53" aria-hidden="true" tabindex="-1"></a></span>
|
||||
<span id="cb5-54"><a href="#cb5-54" aria-hidden="true" tabindex="-1"></a><span class="fu">### Safety rails</span></span>
|
||||
<span id="cb5-55"><a href="#cb5-55" aria-hidden="true" tabindex="-1"></a></span>
|
||||
<span id="cb5-56"><a href="#cb5-56" aria-hidden="true" tabindex="-1"></a>• Never touch production data. • Assume all work happens in a feature branch,</span>
|
||||
<span id="cb5-57"><a href="#cb5-57" aria-hidden="true" tabindex="-1"></a>never commit directly to main. • Check the generated Document with</span>
|
||||
<span id="cb5-58"><a href="#cb5-58" aria-hidden="true" tabindex="-1"></a><span class="in">`markdownlint`</span> (if available), apply auto-fixes and fix the remaining issues</span>
|
||||
<span id="cb5-59"><a href="#cb5-59" aria-hidden="true" tabindex="-1"></a>manually.</span></code><button title="In die Zwischenablage kopieren" class="code-copy-button"><i class="bi"></i></button></pre></div>
|
||||
<span id="cb5-16"><a href="#cb5-16" aria-hidden="true" tabindex="-1"></a><span class="ss">- </span>Create /tasks/<span class="dt"><</span><span class="kw">feature</span><span class="dt">></span>/TASKS.md (overwrite if it exists).</span>
|
||||
<span id="cb5-17"><a href="#cb5-17" aria-hidden="true" tabindex="-1"></a><span class="ss">- </span>Markdown only, no prose around it.</span>
|
||||
<span id="cb5-18"><a href="#cb5-18" aria-hidden="true" tabindex="-1"></a><span class="ss">- </span>Epics = H2 headings (<span class="in">`## 1. <Epic>`</span>).</span>
|
||||
<span id="cb5-19"><a href="#cb5-19" aria-hidden="true" tabindex="-1"></a><span class="ss">- </span>Tasks = unchecked check‑boxes (<span class="in">`- [ ] 1.1 <task>`</span>).</span>
|
||||
<span id="cb5-20"><a href="#cb5-20" aria-hidden="true" tabindex="-1"></a><span class="ss">- </span>Sub‑tasks = indent one space under their parent (<span class="in">` - [ ] 1.1.1 <subtask>`</span>).</span>
|
||||
<span id="cb5-21"><a href="#cb5-21" aria-hidden="true" tabindex="-1"></a><span class="ss">- </span>Create a /tasks/<span class="dt"><</span><span class="kw">feature</span><span class="dt">></span>/Task*<Epic>*<span class="dt"><</span><span class="kw">task</span><span class="dt">></span><span class="sc">\_</span><span class="dt"><</span><span class="kw">subtask</span><span class="dt">></span>.md (i.e.</span>
|
||||
<span id="cb5-22"><a href="#cb5-22" aria-hidden="true" tabindex="-1"></a> <span class="in">`Task_3_2_4.md`</span> for Epic 3, Task 2, Subtask 4)</span>
|
||||
<span id="cb5-23"><a href="#cb5-23" aria-hidden="true" tabindex="-1"></a></span>
|
||||
<span id="cb5-24"><a href="#cb5-24" aria-hidden="true" tabindex="-1"></a><span class="fu">### Process</span></span>
|
||||
<span id="cb5-25"><a href="#cb5-25" aria-hidden="true" tabindex="-1"></a></span>
|
||||
<span id="cb5-26"><a href="#cb5-26" aria-hidden="true" tabindex="-1"></a><span class="ss">1. </span>Read the tagged PRD.</span>
|
||||
<span id="cb5-27"><a href="#cb5-27" aria-hidden="true" tabindex="-1"></a><span class="ss">2. </span>**Investigate** the current state of the repository to collect answers to</span>
|
||||
<span id="cb5-28"><a href="#cb5-28" aria-hidden="true" tabindex="-1"></a> your first questions. All specs for fixed behaviours and outputs are located</span>
|
||||
<span id="cb5-29"><a href="#cb5-29" aria-hidden="true" tabindex="-1"></a> in <span class="in">`specs/`</span>. **Consult those** as a source first before trying to</span>
|
||||
<span id="cb5-30"><a href="#cb5-30" aria-hidden="true" tabindex="-1"></a> reverse-engineer from the code. </span>
|
||||
<span id="cb5-31"><a href="#cb5-31" aria-hidden="true" tabindex="-1"></a> If specs are in need of change then this is also a task to be generated.</span>
|
||||
<span id="cb5-32"><a href="#cb5-32" aria-hidden="true" tabindex="-1"></a><span class="ss">3. </span>If critical info is missing and cannot be answered by looking at the code,</span>
|
||||
<span id="cb5-33"><a href="#cb5-33" aria-hidden="true" tabindex="-1"></a> ask max five clarifying questions (Q1 … Q5) and stop until answered.</span>
|
||||
<span id="cb5-34"><a href="#cb5-34" aria-hidden="true" tabindex="-1"></a><span class="ss">4. </span>After questions are answered think about the answers and: Either: look at the</span>
|
||||
<span id="cb5-35"><a href="#cb5-35" aria-hidden="true" tabindex="-1"></a> code again, then goto 3., and ask for further clarification Or: Reply</span>
|
||||
<span id="cb5-36"><a href="#cb5-36" aria-hidden="true" tabindex="-1"></a> exactly: Ready to generate the subtasks – respond **go** to proceed.</span>
|
||||
<span id="cb5-37"><a href="#cb5-37" aria-hidden="true" tabindex="-1"></a><span class="ss">5. </span>On a user message that contains only the word "go" (case‑insensitive): a.</span>
|
||||
<span id="cb5-38"><a href="#cb5-38" aria-hidden="true" tabindex="-1"></a> Generate /tasks/<span class="dt"><</span><span class="kw">feature</span><span class="dt">></span>/TASKS.md following _Output_ spec. b. Reply with:</span>
|
||||
<span id="cb5-39"><a href="#cb5-39" aria-hidden="true" tabindex="-1"></a> TASKS.md created – review them.</span>
|
||||
<span id="cb5-40"><a href="#cb5-40" aria-hidden="true" tabindex="-1"></a><span class="ss">6. </span>After TASKS.md was reviewed, create <span class="in">`Task_<e>_<t>_<s>.md`</span> for each task and</span>
|
||||
<span id="cb5-41"><a href="#cb5-41" aria-hidden="true" tabindex="-1"></a> subtask containing implementation hints like relevant specs (link them!),</span>
|
||||
<span id="cb5-42"><a href="#cb5-42" aria-hidden="true" tabindex="-1"></a> primary files to edit/review for this task, tests needing change, etc.</span>
|
||||
<span id="cb5-43"><a href="#cb5-43" aria-hidden="true" tabindex="-1"></a><span class="ss">7. </span>Stop. Do **not** begin executing tasks in this rule.</span>
|
||||
<span id="cb5-44"><a href="#cb5-44" aria-hidden="true" tabindex="-1"></a></span>
|
||||
<span id="cb5-45"><a href="#cb5-45" aria-hidden="true" tabindex="-1"></a><span class="fu">### Writing guidelines</span></span>
|
||||
<span id="cb5-46"><a href="#cb5-46" aria-hidden="true" tabindex="-1"></a></span>
|
||||
<span id="cb5-47"><a href="#cb5-47" aria-hidden="true" tabindex="-1"></a><span class="ss">- </span>Each item ≤120 characters, start with an action verb.</span>
|
||||
<span id="cb5-48"><a href="#cb5-48" aria-hidden="true" tabindex="-1"></a><span class="ss">- </span>Hints are allowed below each item as HTML-Comment and do not count against the</span>
|
||||
<span id="cb5-49"><a href="#cb5-49" aria-hidden="true" tabindex="-1"></a> 120 characters.</span>
|
||||
<span id="cb5-50"><a href="#cb5-50" aria-hidden="true" tabindex="-1"></a><span class="ss">- </span>Group related work into logical epics with ≤7 direct child items.</span>
|
||||
<span id="cb5-51"><a href="#cb5-51" aria-hidden="true" tabindex="-1"></a><span class="ss">- </span>Prefer concrete file paths, commands, specs or APIs when available.</span>
|
||||
<span id="cb5-52"><a href="#cb5-52" aria-hidden="true" tabindex="-1"></a><span class="ss">- </span>Skip implementation details obvious from the codebase in the overview.</span>
|
||||
<span id="cb5-53"><a href="#cb5-53" aria-hidden="true" tabindex="-1"></a><span class="ss">- </span>If a task only concerns up to 5 files, name them in the detailed file.</span>
|
||||
<span id="cb5-54"><a href="#cb5-54" aria-hidden="true" tabindex="-1"></a> Otherwise give hints on how to search for them (i.e. "everything under</span>
|
||||
<span id="cb5-55"><a href="#cb5-55" aria-hidden="true" tabindex="-1"></a> <span class="in">`src/models/`</span>").</span>
|
||||
<span id="cb5-56"><a href="#cb5-56" aria-hidden="true" tabindex="-1"></a></span>
|
||||
<span id="cb5-57"><a href="#cb5-57" aria-hidden="true" tabindex="-1"></a><span class="fu">### Safety rails</span></span>
|
||||
<span id="cb5-58"><a href="#cb5-58" aria-hidden="true" tabindex="-1"></a></span>
|
||||
<span id="cb5-59"><a href="#cb5-59" aria-hidden="true" tabindex="-1"></a><span class="ss">- </span>Never touch production data.</span>
|
||||
<span id="cb5-60"><a href="#cb5-60" aria-hidden="true" tabindex="-1"></a><span class="ss">- </span>Assume all work happens in a feature branch, never commit directly to main.</span>
|
||||
<span id="cb5-61"><a href="#cb5-61" aria-hidden="true" tabindex="-1"></a><span class="ss">- </span>Check the generated Document with <span class="in">`markdownlint`</span> (if available), apply</span>
|
||||
<span id="cb5-62"><a href="#cb5-62" aria-hidden="true" tabindex="-1"></a> auto-fixes and fix the remaining issues manually.</span></code><button title="In die Zwischenablage kopieren" class="code-copy-button"><i class="bi"></i></button></pre></div>
|
||||
</div>
|
||||
<p>This also works better with one of those deep-thinking models.</p>
|
||||
</section>
|
||||
@ -1256,7 +1275,7 @@ This is most often the most trivial step. Everything is known and formulated for
|
||||
</section>
|
||||
<section id="example-rules-in-action" class="level2 page-columns page-full">
|
||||
<h2 class="anchored" data-anchor-id="example-rules-in-action">Example: Rules in Action</h2>
|
||||
<p>The codebase we look at here is a project called <code>gitlab_overviewer</code>. It takes gitlab-api-keys and generates nice overviews for tracking metadata in different projects across different groups. With a nice export to markdown (for rendering in gitlab itself) and quarto (for exporting to i.e. confluence) with multiple pages etc. pp.</p>
|
||||
<p>The codebase we look at here is a project called <code>gitlab_overviewer</code>. It takes GitLab-api-keys and generates nice overviews for tracking metadata in different projects across different groups. With a nice export to markdown (for rendering in GitLab itself) and quarto (for exporting to i.e. confluence) with multiple pages etc. pp.</p>
|
||||
<p>The current issue is, that due to a complete rewrite we are happy with the current output, but there are some minor problems still remaining. Some of them may also due to specs being incorrect, because requirements or ideas changed over time.</p>
|
||||
<section id="analyzing-the-situation" class="level3 page-columns page-full">
|
||||
<h3 class="anchored">Analyzing the situation</h3>
|
||||
@ -1728,7 +1747,7 @@ Cursor
|
||||
<li><strong>Project Integrity</strong>: Through rigorous spec adherence and systematic task breakdown, the codebase is more consistent, much better documented and decently tested<a href="#fn5" class="footnote-ref" id="fnref5" role="doc-noteref"><sup>5</sup></a>.</li>
|
||||
<li><strong>Reduced Cognitive Load</strong>: The Cursor rule system has made it easier to focus on actual development tasks instead of wrestling with the AI’s sometimes questionable assumptions - or just installing a third different testing framework for exactly this module.</li>
|
||||
</ul>
|
||||
<div class="no-row-height column-margin column-container"><div id="fn5"><p><sup>5</sup> You know.. noone likes writing tests - and the person writing the code should never write the tests anyway. If you haven’t thought of something while coding, chanches are, that you miss that edge-case during testing as well.</p></div></div><p>In this <code>gitlab_overviewer</code> case study, i tried to show at an easy example, that this method works and <em>can</em> yields great outcomes. Even small discrepancies in the codebase tend to pop up during spec-reviews (which can be automated!). Next up would be running those in some kind of CI-job and integrating tools like issue-tracking into the agent instead of simple markdown-files in the repository as makeshift issue-tracker. But not by me for the forseeable future, so if you are looking for a project, feel free!</p>
|
||||
<div class="no-row-height column-margin column-container"><div id="fn5"><p><sup>5</sup> You know.. noone likes writing tests - and the person writing the code should never write the tests anyway. If you haven’t thought of something while coding, chanches are, that you miss that edge-case during testing as well.</p></div></div><p>In this <code>gitlab_overviewer</code> case study, i tried to show at an easy example, that this method works and <em>can</em> yields great outcomes. Even small discrepancies in the codebase tend to pop up during spec-reviews (which can be automated!). Next up would be running those in some kind of CI-job and integrating tools like issue-tracking into the agent instead of simple markdown-files in the repository as makeshift issue-tracker. But not by me for the foreseeable future, so if you are looking for a project, feel free!</p>
|
||||
<p><strong>All in all this isn’t a silver bullet for all AI-assisted development problems, but it’s made my coding experience with Cursor much more productive and predictable. It turns out treating an AI as a slightly overeager junior developer who needs clear instructions works better than hoping it’ll just “do the right thing”.</strong></p>
|
||||
|
||||
|
||||
|
||||
Reference in New Issue
Block a user