Microsoft/bcquality
1
0
Fork 0
mirror of https://github.com/microsoft/BCQuality.git synced 2026-08-07 01:46:53 +01:00
Code Issues Projects Releases Packages Wiki Activity Actions

Add best practices and anti-patterns for Azure integration batching and error classification

Browse source
This commit is contained in:
Tharanga Chandrasekara 2026-06-07 12:50:15 +12:00
parent 07140e2223
commit 01bee2f23f
11 changed files with 210 additions and 237 deletions
Download patch file Download diff file Expand all files Collapse all files

29
custom/knowledge/process/ground-work-in-a-solution-constitution.md
View file

@ -1,29 +0,0 @@
---
bc-version: [all]
domain: process
keywords: [constitution, brief, tech-design, roadmap, project-context, sdd]
technologies: [al]
countries: [w1]
application-area: [all]
---
# Ground work in a solution constitution
## Description
A Business Central solution should maintain a small set of durable, high-level documents (the constitution) that every feature spec is grounded in: a project brief (customer and localisation, business processes, goals, non-goals, constraints, success measures), a technical design (architecture, which standard BC modules to reuse, the honest custom-code gaps, the assigned object ID range, the high-level data model, integrations, cross-cutting concerns), and a roadmap (an ordered, numbered feature list with status). These are the documents every agent and engineer reads before doing anything, so individual feature work stays consistent with the agreed direction instead of each feature re-deciding the architecture.
The constitution exists so that decisions are made once and reused, not re-litigated per feature. The brief fixes the business intent, the technical design fixes the architecture and the object ID range, and the roadmap fixes the order and the numbering that feature folders follow. Because every spec is checked against all three, the documents are where solution-wide consistency actually lives; without them each feature quietly invents its own answer to questions the solution already decided.
## Best Practice
Establish the constitution once at the start of a solution, and refresh rather than rewrite it when the business need changes materially, preserving decisions still valid. Interview for missing facts rather than inventing them. Write the brief in plain language with no AL, the technical design favouring reuse of standard BC and justifying every custom-code gap, and the roadmap as a numbered feature list so feature folders match the numbering. Treat the constitution as a human decision: stop for review before proceeding to feature specs. Every feature spec must then be consistent with all three documents.
## Anti Pattern
Specifying or building features with no shared brief, technical design, or roadmap to ground them. The consequence is features that contradict each other on architecture, object ID ranges, or which standard modules to reuse, because each one re-decides in isolation. The signal: feature specs that exist with no constitution behind them, or custom AL introduced with no recorded justification for not reusing standard BC.
## See also
- `specify-before-you-build.md`
- `map-each-feature-to-an-object-id-range.md`

29
custom/knowledge/process/specify-before-you-build.md
View file

@ -1,29 +0,0 @@
---
bc-version: [all]
domain: process
keywords: [spec, specification, acceptance-criteria, requirements, sdd, before-implementation]
technologies: [al]
countries: [w1]
application-area: [all]
---
# Specify before you build
## Description
Before planning or writing any AL for a Business Central feature, write a feature specification that captures the problem, the users and roles, the scope and out-of-scope edges, the user flow, and testable acceptance criteria. The spec is the what and why; it deliberately names no AL objects. Writing it first grounds the work in agreed requirements and makes the result verifiable: each acceptance criterion is concrete enough to become a test, so "done" is something you can check rather than something you argue about after the code exists.
Keeping AL out of the spec is deliberate, not an omission. Naming objects too early collapses the what into the how and quietly commits the design before anyone has agreed what the feature must do. The acceptance criteria are the load-bearing part: they are written so each one maps to a single test, which means the spec doubles as the test plan and the definition of done is fixed before any code can drift away from it.
## Best Practice
For each feature, produce a spec before the plan and before any code. State the problem and the affected users and roles, draw the scope and out-of-scope boundaries, describe the user flow, and write acceptance criteria concrete enough to turn directly into tests. Record genuinely open items under open questions rather than guessing, and stop for human review of the spec before planning or implementing. Keep AL object names out of the spec; those belong to the planning step. At implementation, confirm every acceptance criterion is covered by a passing test.
## Anti Pattern
Jumping into AL with only an informal idea of the feature and no written, reviewable acceptance criteria. The consequence is scope that drifts during coding, no shared definition of done, and a result that cannot be verified against agreed requirements. The signal: a feature being implemented with no spec, or a spec that lists vague goals instead of testable acceptance criteria, or one that has already committed to AL object names before the what and why are agreed.
## See also
- `ground-work-in-a-solution-constitution.md`
- `map-each-feature-to-an-object-id-range.md`