Topic: Part 6. Constitution of the Bank's Data Platform
Difficulty level: Medium
Estimated study time: 3-4 hours (theory — 1.5 h, practice — 1.5 h, case studies — 1 h)
Prerequisites: Basic understanding of Data Lakehouse architecture
Familiarity with the principles of dbt and DuckDB
Understanding of the concepts of grain, freshness, and data contracts
Experience working with analytical data marts
Basic knowledge of PII policies and personal data protection
Learning objectives: Formulate the mission of the bank's data platform so that it helps the agent make specific decisions
Distinguish which rules belong to the constitution and which to the specification of a particular model
Compose a set of non-negotiable rules (5–10 items) with an explicit indication of where they are recorded
Determine the agent's course of action upon discovering a conflict between the convenience of the mart and long-term principles
Conduct a review of contract changes taking into account breaking changes and requirements for human confirmation
Overview: The data platform constitution is a short but verifiable set of principles that fixes the mission, the allowed stack, the artifact roadmap, and the rules of agent behavior. Unlike a typical technical stack, the constitution answers not only the question "which tools do we use" but also "which decisions the agent does not make on its own." For banking analytics this is critically important: grain, PII policy, SLA, breaking changes, and risk methodology must not appear as a side effect of SQL. This part examines how to assemble the four minimum files (mission.md, tech-stack.md, roadmap.md, AGENTS.md), which rules should become non-negotiable, how to recognize a typical mistake of mixing the constitution and the mart specification, and how to treat the constitution as a contract with your future self.
Key concepts: Data platform constitution: A short and verifiable document (a set of 4 files) that records the mission, stack, roadmap, and agent behavior rules. Answers the question: which decisions do not need to be re-discussed in each mart.
Mission.md: A file explaining why the platform exists. A good mission is concrete and verifiable: "Every data product must have an owner, a consumer, a grain, a PII policy, a freshness promise, check facts, and a reviewer report." A bad one sounds big but does not help make a decision.
Tech-stack.md: A file that records the local stack and its mapping to the production environment. Defines which tools are allowed in the study environment (DuckDB, dbt) and how they correspond to the production environment.
Roadmap.md: A file showing the order of artifacts. Guides the agent and the reviewer through the sequence of steps: what is created earlier and what is created later.
Agents.md: A file setting the rules of agent behavior. Contains non-negotiable restrictions: a ban on PII leakage, a requirement for confirmation when changing grain, a ban on editing files at the review stage.
Non-negotiable rules: Principles that cannot be changed within a separate mart without updating the constitutional file. Examples: marts do not expose direct PII fields; changing grain requires approval; mandatory contract fields cannot be deleted without a breaking change note; dbt build --profiles-dir . is a mandatory check; the reviewer pass must not edit files.
Grain: The level of row granularity in a mart (for example, one row per customer). Changing the grain is a breaking change that requires human approval.
PII (personally identifiable information): Personally identifiable information. The PII policy is fixed in the constitution before source profiling in order to avoid accidental disclosure.
Breaking change: A change in the contract that can break consumers: deletion of a mandatory field, change of grain, change of data type. Requires separate approval and a note.
Data contract: The specification of a data product: owner, consumers, grain, fields, PII policy, freshness SLA, check facts. Described in YAML or in the model specification.
Model specification: A document describing a specific mart (for example, mart_customer_360): SQL fields, business logic, tests. It should not re-select the stack or formulate the mission.
Check facts: Statements that are written before SQL and verified after. They allow you to capture the expected behavior of a model before it is implemented.
Contract with your future self: A metaphor describing the role of the constitution: at the beginning of a project everything is obvious, but after ten changes the obviousness disappears. The constitution preserves the original decisions in a place where the next agent pass and the reviewer will see them.
Important dates: Before the start of source profiling: Record the PII policy in mission.md or AGENTS.md to avoid accidental disclosure during the first data scan.
Before writing SQL: Write down check facts for each model. This rule is included in the constitution as non-negotiable.
Before changing the grain or deleting a mandatory contract field: Stop, update the constitutional file, obtain human confirmation, and only then change the SQL.
When a new rule first appears during implementation: Stop and update the constitutional file before continuing with SQL. Do not leave the rule as a comment in the code.
Practice exercises: Name: Composing five non-negotiable rules
Problem: Compose five non-negotiable rules for your study bank data platform. For each rule, indicate where it lives: AGENTS.md, mission.md, tech-stack.md, contract YAML, or the model specification. The rules must be verifiable, not slogans.
Solution: Step 1. Identify five risks that most often arise when working with banking marts: PII leakage, grain drift, deletion of mandatory fields, skipping the dbt build check, editing files at the review stage. Step 2. Formulate each rule as a statement that can be verified in a review. Step 3. Determine the place of recording:
- Rule 1 "marts do not expose direct PII fields (full name, phone, email in plain text)" → AGENTS.md
- Rule 2 "changing grain requires approval from the product owner and a note in roadmap.md" → AGENTS.md + roadmap.md
- Rule 3 "mandatory contract fields (owner, consumer, grain, sla) cannot be deleted without a breaking change record" → contract YAML + AGENTS.md
- Rule 4 "before merge,
dbt build --profiles-dir .is run; the build must pass without errors" → tech-stack.md + AGENTS.md - Rule 5 "the reviewer does not edit files but leaves comments; the author makes the edits" → AGENTS.md
Step 4. Check each rule: can it be violated in such a way that it is visible in the diff or in the dbt log? If not, reformulate it.
Complexity: intermediate
Name: Distinguishing the constitution from the model specification
Problem: You are given a fragment of a document describing the mart mart_customer_360. Determine which lines belong to the data platform constitution and which belong to the specification of a particular model. Explain why mixing these layers is a typical mistake.
Solution: Step 1. Read the fragment and write down all the statements. Step 2. Classify each statement:
- "The platform uses dbt 1.8 and DuckDB 1.1 in the local environment, and Snowflake in production" → constitution (tech-stack.md), because it is about the stack as a whole.
- "mart_customer_360 contains the fields customer_id, full_name, birth_date, segment_code" → model specification, because it is about a specific mart.
- "Marts do not expose direct PII fields; full_name is masked as Ivanov I.I." → constitution (AGENTS.md) + specification (the masking rule for this particular mart).
- "Grain is one row per customer; changing grain requires approval" → the part about "approval" is the constitution, the part about "one row per customer" is the specification.
Step 3. Formulate the conclusion: the constitution describes general principles and boundaries, the specification describes a concrete implementation. Mixing them leads to the fact that when a new mart appears, you have to re-decide which stack to use, and each decision is made ad hoc.
Complexity: intermediate
Name: Verifiability of mission.md formulations
Problem: You are presented with two formulations of mission.md. Determine which of them is better, and reformulate the bad one so that it becomes verifiable in review.
Solution: Step 1. Read the formulations: A) "Build a modern banking data platform". B) "The platform builds reproducible analytical marts for the study bank. Every data product must have an owner, a consumer, a grain, a PII policy, a freshness promise, check facts, and a reviewer report". Step 2. Compare: formulation A does not give the agent a criterion for making a decision. Formulation B enumerates the mandatory attributes of each data product — they can be verified against contract YAML. Step 3. Reformulate A into a verifiable form: "The platform provides reproducible marts on dbt + DuckDB; each mart is published together with a contract YAML containing owner, consumer, grain, pii_policy, freshness_sla, check_facts, and review_report. The absence of any of the seven attributes is a blocking comment from the reviewer". Step 4. Formulate the rule: a good mission enumerates mandatory attributes or actions, a bad one operates with abstract values.
Complexity: beginner
Name: Agent's reaction to a conflict
Problem: While implementing the mart mart_transactions_daily, the agent discovered that for the analyst's convenience it was necessary to add the column card_pan_hash, which is a direct PII field. Describe the correct sequence of actions for the agent in accordance with the constitution.
Solution: Step 1. The agent must stop and not add the field until clarified. Step 2. The agent checks AGENTS.md: "marts do not expose direct PII fields". The field card_pan_hash belongs to PII. Step 3. The agent checks whether there is an exception for hash values in mission.md or AGENTS.md. If there is no exception, the field cannot be added to the mart. Step 4. The agent formulates a request: either change the PII policy in the constitution (with human confirmation), or offer the analyst an alternative (for example, the aggregated metric count_distinct_pan). Step 5. Only after human approval and updating the constitutional file does the agent continue working with SQL. Step 6. If there is no constitution in the project, the agent must stop and ask for it to be created, rather than making the decision on its own.
Complexity: intermediate
Name: Composing a Qwen request for creating the constitution
Problem: Compose a request to the agent (following the pattern from the chapter) that will help assemble the constitution of the study bank data platform. The request must be self-contained and explicitly prohibit premature SQL writing.
Solution: Step 1. Determine the goal of the request: to assemble the four constitution files (mission.md, tech-stack.md, roadmap.md, AGENTS.md). Step 2. List the mandatory blocks of questions that the agent must get answers to before writing: mission, stack, PII policy, contract drift, human confirmations. Step 3. Add an explicit prohibition: "Do not write SQL". Step 4. The final request: "Help me compose the constitution of the study bank data platform. Before writing the files, ask questions about the mission, stack, PII policy, contract drift, and human confirmations. Do not write SQL". Step 5. Check: the request starts with the goal, lists the mandatory clarifications, and ends with a prohibition. Such a request prevents the situation where the agent immediately writes SQL without a constitution.
Complexity: beginner
Case studies: Name: Grain drift in the customer segments mart: a lesson for the constitution
Scenario: A mart mart_customer_segment with the grain "one row per customer per month" was deployed in the study bank. After six iterations the analyst asked to add a breakdown by products: "one row per customer and product per month". The agent, without stopping, changed the SQL and updated the model. The consumer — the segmentation dashboard — stopped working because it expected one row per customer.
Challenge: The agent made the decision to change the grain on its own, without the approval of the product owner. The project did not have a constitutional file recording the rule: "changing grain requires approval". Each grain change had to be discussed anew, and almost always the option "as convenient now" was chosen.
Solution: The team stopped work on the marts and assembled the constitution of four files. In AGENTS.md the rule appeared: "Changing grain requires approval from the data product owner and an entry in roadmap.md. The agent does not change grain on its own". In mission.md the list of mandatory attributes of each data product was added, including grain. In the contract YAML of mart_customer_segment the grain was recorded and marked as a mandatory field that cannot be deleted without a breaking change.
Result: Two weeks after the introduction of the constitution, a new request was received to change the grain in mart_risk_flags. The agent stopped, formulated an approval request, updated roadmap.md, and only after the owner's consent changed the SQL. The dashboards continued to work. The time for reviewing grain changes decreased, because the rule became verifiable: the reviewer sees the grain diff in contract YAML.
Lessons learned: The rule "changing grain requires approval" should live in AGENTS.md, not in a SQL comment.
Grain is a mandatory field of contract YAML; its deletion or change is a blocking comment from the reviewer.
Without a constitution, each grain change is discussed anew and the nearest task almost always wins.
Related concepts: Grain
Non-negotiable rules
AGENTS.md
Contract with your future self
Name: PII leakage through a convenient column: how the constitution stopped the regression
Scenario: In the mart mart_transactions_weekly, the analyst asked to add the column counterparty_name in order to see the names of counterparties. The agent added the field without checking the PII policy. A month later it turned out that the column had begun to be used in reports for external partners, and some names leaked outside the bank's perimeter.
Challenge: The PII policy existed as a general phrase in the project's README: "Comply with the requirements for the protection of personal data". The wording was not verifiable, and the reviewer could not block the change on a formal basis. In addition, the policy was recorded too late — already after source profiling, when counterparty names were already visible in the samples.
Solution: The team reworked the constitution. In AGENTS.md a specific rule appeared: "Marts do not expose direct PII fields: full name, phone, email, counterparty name in plain text. Masked representation (for example, 'Ivanov I.I.') or aggregates (count, sum without identifiers) are allowed". The policy was recorded before source profiling in the next sprint. In the contract YAML of each mart, a mandatory field pii_policy appeared, which is filled in by the author and checked by the reviewer.
Result: Three sprints later, a similar request was received: add the field counterparty_inn (counterparty TIN). The agent stopped, checked AGENTS.md and discovered that TIN is not in the list of direct PII, but belongs to sensitive commercial information. The agent formulated a request to clarify the policy, the product owner confirmed that TIN is allowed only in masked form, and the policy was updated in AGENTS.md. The leakage stopped, and the reviewer now blocks PRs without a filled-in pii_policy.
Lessons learned: The PII policy must be concrete and verifiable: enumerate fields rather than appeal to general principles.
The PII policy must be recorded before source profiling, otherwise the first samples create the illusion of safety.
The mandatory field pii_policy in contract YAML turns the policy from a slogan into a blocking comment from the reviewer.
Related concepts: PII (Personally Identifiable Information)
Non-negotiable rules
mission.md
Data contract
Name: The reviewer edits SQL and breaks reproducibility: a lesson about role boundaries
Scenario: The team had an established process: the reviewer opens a PR, makes edits to SQL directly, and merges. After half a year it turned out that some models in the main branch are not reproducible locally: dbt build fails with an error because the reviewer used a function that is not in the recorded stack.
Challenge: There was no rule in the project that "the reviewer does not edit files". The reviewer's role was blurred: they both checked and edited at the same time. The verifiability of the constitution's rules decreased, because the reviewer could "quietly" circumvent any restriction simply by fixing the code.
Solution: In AGENTS.md the rule was added: "The reviewer's pass must not edit files. The reviewer leaves comments and sets the status check; the author makes the edits in the next commit". In tech-stack.md the minimum version of dbt and DuckDB was recorded, and in roadmap.md a step was added: "Before merge, dbt build --profiles-dir . is run; a green build is a mandatory condition".
Result: During the next month, three PRs were rejected on a formal basis: the reviewer left a comment, the author made the fix, and a repeated run of dbt build passed. The reproducibility of the local environment was restored. The team also recorded that any new dependencies are first added to tech-stack.md and only then to the code.
Lessons learned: The reviewer's role is to check, not to edit. Mixing roles blurs the constitution.
dbt build --profiles-dir . is a mandatory check; it must be recorded in tech-stack.md and roadmap.md.
Tool versions are part of the stack, not an implementation detail; changing them requires updating tech-stack.md.
Related concepts: Non-negotiable rules
tech-stack.md
roadmap.md
AGENTS.md
Study tips: Keep the constitution short: four files of 1–2 pages each is better than one document of twenty pages. Long documents are not read by either agents or reviewers.
Before writing mission.md, ask yourself: "Can the agent make a specific decision in a controversial situation based on this mission?" If the answer is "no", reformulate it.
Formulate each non-negotiable rule so that it can be verified in a diff or in the build log. The phrase "maintain quality" is a slogan. The phrase "marts do not expose the field full_name" is a rule.
Record the PII policy before source profiling. After the first sample you will already have the illusion that "it's not so bad", and the policy will be postponed.
When a new rule first appears during implementation, stop and update the constitutional file. Do not leave the rule as a comment in SQL: the next agent will not see it.
Separate mission.md (why), tech-stack.md (with what), roadmap.md (in what order), AGENTS.md (what is not allowed), and the model specification (what exactly is being built). Mixing these layers is the main source of errors.
Treat the constitution as a contract with your future self. What is obvious today will cease to be obvious after ten changes.
Use the request "Help me compose the constitution... Do not write SQL" as a template: goal, mandatory clarifications, prohibition of premature actions.
When reviewing, first check the constitutional rules (PII, grain, mandatory fields), then the SQL. This speeds up the review and makes comments blocking on a formal basis.
Additional resources: The base volume of the course (application constitution): Describes the mission, stack, and roadmap of the application as a whole; part 6 extends this idea to Data Lakehouse.
dbt documentation on data contracts: https://docs.getdbt.com — the section on data contracts and model schemas.
DuckDB documentation: https://duckdb.org/docs — a description of the local analytical engine used in the study environment.
The "Data Mesh" framework (Zhamak Dehghani): The concept of domain ownership and data contracts underlying the idea of a constitution file.
GDPR and bank regulatory requirements: An overview of the requirements for the protection of personal data in the financial sector (for the context of PII policy).
The article "The Ten Fallacies of Data Science": About common mistakes in building analytical platforms, including the absence of an explicit policy.
Summary: The constitution of the bank's data platform is four short files (mission.md, tech-stack.md, roadmap.md, AGENTS.md) that record the mission, the allowed stack, the artifact roadmap, and the non-negotiable rules of agent behavior. The main value of the constitution lies in its verifiability: each rule must be formulated so that it can be applied in review. A bad constitution says "maintain quality and security", a good one says "marts do not expose direct PII", "changing grain requires confirmation", "check facts are written before SQL". The constitution must be assembled before source profiling, updated when a new rule appears, and treated as a contract with your future self: what is obvious today will cease to be obvious after ten changes. A typical mistake is mixing the constitution and the specification of a specific mart; this should be avoided by separating general principles and implementation across different layers of documentation.