AACE AI SW
👤ParticipantACE AI SW
DAY 04 · THURSDAY · REAL PROJECT 2 · BUILD

Building with Antigravity:
driving AI
with MD documents

Antigravity's AI agent works by reading Markdown files inside the project, not the chat window. Today you design rule MDs (AGENTS.md · Rules), spec MDs (planning · data · API · verification) and log MDs (work log · decision log), add the MDs you need yourself, and build a working service one requirement ID at a time.

A prompt disappears when the chat ends, but MD files stay and give the next AI task the same standard. So "how to leave things well" comes before "how to ask well".

HTML Presentation

Day 4 Slides · MD-Based AI Development

Use the arrow buttons or keyboard arrow keys (←/→) to move. Press the button (or the N key) to open the lecture notes for each slide.

ACE AI SW Startup Training · Day 4

Markdown is the
Interface to AI.

The surest way to get good code from Antigravity is not a longer prompt, but creating MD documents AI can re-read every time inside the project.

AGENTS.mdrules/*.mdspec.mdLOG.mdAntigravityRe-read every timeSame standard
01 · RulesAGENTS.md · .agents/rules — rules to always follow
02 · SpecsPlanning · data · API · verification — what to build
03 · Build/plan → review → build — one requirement at a time
04 · TraceAI_WORK_LOG · DECISION_LOG — record and link
Opening question

"Antigravity, build me an ordering kiosk."
Will you get the same app yesterday and today?

Developing by chat only

  • Structure, names and colors change with every request
  • A new chat forgets earlier decisions
  • It adds features you didn't ask for "on its own"
  • No standard to judge what's right

Developing with MD docs

  • AGENTS.md injects the same rules into every chat
  • IDs in spec MDs lock the scope exactly
  • Decisions stay in DECISION_LOG for the next AI to read
  • "Done" is judged by acceptance criteria
AI's memory lives in the file system, not the chat window. A decision you didn't record is a decision that doesn't exist for the AI in the next chat.
Analogy · Shift work

AI is a worker who starts fresh every shift; MD is the handover note

Shift change without handoverMonday worker"Show sold-out items in grey"Tuesday worker"Sold out? First I've heard of it…"New chat = no memoryPromises in the chat window don't carry to the next chatWith handover notes (MD)Monday workerTuesday workerAGENTS.md"The notes say sold out = grey · can't order"AI's memory is in files, not the chat window
Why Markdown?

MD is the only contract people and AI both read

Both read itPeople and AI understand heading, table and checklist structure the same way
Versions stayTrack who changed what, when and why with Git, and roll back
Point exactlyName the exact doc in chat, like @order-flow.md
Works across toolsAntigravity · Codex · Claude Code read the same AGENTS.md
The 3-layer MD stack

Split project MDs into 3 layers + 1

The house where AI worksLayer 1 · Rules"How to work" — always appliesAGENTS.md · .agents/rules/*.md · ~/.gemini/GEMINI.mdLayer 2 · Specs"What to build"service-planning/ · service-analysis/Layer 3 · Logs"What was done and why it was decided"DECISION_LOG · AI_WORK_LOG · TRACEABILITY+1 · Procedures (Skills)Recipes for repeated work.agents/skills/name/SKILL.mdCall with /name
Before making a new MD, ask: "Is this a rule, a spec, a log or a procedure?" If you pick the wrong layer, AI reads it at the wrong time or not at all.
Analogy · School

Understand MD 3 layers + 1 as a school

Layer 1 · RulesSchool rulesAlways follow
AGENTS.md.agents/rules/
"If it differs from the docs, ask first"
Layer 2 · SpecsAssignment sheetWhat to build this time
service-planning/service-analysis/
"REQ-004 cart quantity 1–10"
Layer 3 · LogsLearning journal · registerWhat we did and why
DECISION_LOGAI_WORK_LOG
"DEC-003 payment out of MVP"
+1 · ProceduresLab procedure sheetRecipes for repeated work
.agents/skills/
“/build-req REQ-004”
HANDS-ON 0110 minTeam · sorting game

Which layer does this belong to?

GoalBefore making a new MD, choose whether it goes in rules · specs · logs · procedures
RuleRules · school rulesAlways follow
SpecSpecs · assignment sheetWhat to build now
LogLogs · learning journalWork done · decisions
ProcedureSkills · lab procedure sheetRepeated recipe
Question"Always follow?" → rule · "Building it now?" → spec · "Already done?" → log · "Same steps every time?" → procedure
If it differs from the docs, suggest fixing the docs first, not the code
Answer: Rule
REQ-004 cart quantity 1–10; at 0, confirm deletion
Answer: Spec
AI-002 changed colors on its own → rejected and re-requested
Answer: Log
Go in order: build → test → log → update trace table
Answer: Procedure
Always answer in English and write code comments in English
Answer: Rule
DEC-003 payment is out of the MVP (owner: PM)
Answer: Log
0 / 6 sorted
0/4
Tick the boxes
to check yourself
Career linkOrganizing information in the right place is a basic work skill every company expects from new hires.
Where Antigravity reads MD

Where AI reads automatically and where it reads only when called

Example workspace structure

kiosk-pbl/
├── AGENTS.md            ← auto · always applied (project constitution)
├── .agents/
│   ├── rules/           ← auto · applied by trigger
│   │   ├── doc-contract.md
│   │   ├── frontend-style.md
│   │   └── safety.md
│   └── skills/          ← loaded by /name or when intent matches
│       ├── build-req/SKILL.md
│       └── doc-audit/SKILL.md
├── service-planning/    ← manual · @mention / doc map
├── service-analysis/
├── service-implementation/
└── service-validation/

Global rules (all projects)

  • ~/.gemini/GEMINI.md or ~/.gemini/AGENTS.md
  • ~/.gemini/config/rules/*.md
  • e.g. "Always answer in English, and write code comments in English"

Size limits

  • A rule file that's too long gets cut off
  • Always-on rules share a token budget
  • → Keep rules short; link long content to spec MDs
Rule activation · trigger

Design rules down to when they get read

If every rule is always_on, important rules get buried. Choose the trigger by asking "Is it always needed?"

always_onAlways appliedInjected in full in every chat. Only short, absolute rules, like docs-first and don'ts.e.g. doc-contract.md
globFile patternApplied automatically only when handling certain files, like globs: **/*.css, **/styles/**.e.g. frontend-style.md
model_decisionAI decidesOnly the description shows first; AI reads the whole thing when the task fits.e.g. safety.md (personal data · payment)
manualOnly when @mentionedIncluded only when you call it directly in chat, like @release-check.e.g. release-check.md
Analogy · Light switches

Understand when rules turn on using lights

Always-on lightalways_onRead in full every chatOnly short, absolute rulese.g. doc-contract.mdSensor lightglobTurns on when you touch certain files (*.css)Rules per file typee.g. frontend-style.mdSmart lightmodel_decisionAI reads the description and turns it on if neededSpecialist rules needed sometimese.g. safety.mdWall switchmanualOnly when you turn it on with @mentionRules used only on special occasionse.g. release-check.md
HANDS-ON 0210 minPairs · quiz

Which switch turns this rule on?

GoalChoose when each rule should be read to avoid wasting tokens and burying rules
always_onAlways-on lightShort, absolute rules
globSensor lightWhen touching certain files
model_decisionSmart lightAI decides when needed
manualWall switchOnly when @mentioned
1
Read the ruleWhat does it protect?
2
When is it needed?Always? Certain files? Sometimes?
3
Choose a switchCheck with the button
4
Give your reasonExplain to your partner
Docs-first principle · don'ts (doc-contract.md)
✓ always_on — a short core rule to follow every time
Use only design tokens in *.css files
✓ glob — needed only when touching CSS files
Caution rules for handling personal data · payment (safety.md)
✓ model_decision — AI decides to read it for related tasks
Final pre-deploy checklist (release-check.md)
✓ manual — called directly only when deploying
**/*.test.js rules for writing tests
✓ glob — needed only when touching test files
Correct 0 / 5
0/4
Tick the boxes
to check yourself
Career linkDeciding "what to do always and what only when needed" is the core of designing work automation.
AGENTS.md = project constitution

Write only 6 blocks in AGENTS.md

AGENTS.md (summary)

# Sandwich Ordering Kiosk
Customers order on mobile; the admin manages orders and sold-out items on PC

## Doc map
- Screens · flows → service-planning/customer-order/*.md
- Admin → service-planning/admin/*.md
- Shared policy · status values → service-planning/common/service-policies.md
- Metrics · events → service-analysis/*.md
- Verification → service-validation/*.md

## Way of working
- One requirement ID at a time, plan before code
- If it differs from the docs, suggest docs first, not code

AGENTS.md anatomy

AGENTS.md① One-line definitionWho · what② Doc mapMD path to read per question ★③ Tech stackRun · test commands④ Way of workingBy ID · plan first⑤ Don'tsPersonal data · copying · unrequested features⑥ Definition of done0 console errors · 360px

Spec MDs aren't read automatically. The doc map is AI's guide.

HANDS-ON 0315 minSolo · write

Create AGENTS.md for your project

GoalWrite the project constitution (6 blocks) that AI reads in every chat
1
Fill 6 boxesShort · specific
2
Auto-buildLive preview
3
Copy · saveIn the project root
4
Check with AI"Summarize AGENTS.md"
KeyWithout ② the doc map, AI doesn't know where the spec MDs are. Write the path to read for each question.
0 / 6

AGENTS.md · live

0/4
Tick the boxes
to check yourself
Career linkAGENTS.md is like a team onboarding doc. People who can write the doc a new teammate (human or AI) reads on day one become leaders.
Spec package · traceable chain

Spec MDs get their power when linked in an ID chain

PlanningPROJECT_BRIEF
DECISION_LOG
service-policies
Screensmobile-screen-spec
pc-screen-spec
design-concept
DataMENU_DATA
Order status definitions
API · analyticsAPI_CONTRACT
analysis-definition
analytics-api
Verificationdesign-validation
service-validation
test-data
REQ-004Requirement · cart quantity · totalUI-C04Screen · cart screenDATA-cartData · cart item structureAPI-003API · create orderTEST-006Test · check total calculationTRACE-ABILITY.md
Where the chain breaks, AI starts guessing. Guessed code will always clash with the next requirement.
Good spec vs vague spec

A spec AI can build = ID + rules + states + acceptance criteria

"Change quantity conveniently"− 1 + buttonsDropdown 1–99Type a numberIf vague → different result every chatREQ-004 quantity 1–10At 0, confirm deletionAlways the same resultIf clear → same result whoever builds it

Vague spec

## Cart
- You can change quantity conveniently
- The total is shown
- It tells you if there's an error
  • AI interprets "conveniently" however it likes
  • No max quantity, empty state or failure state
  • No standard to judge done

Buildable spec

## REQ-004 Cart quantity · total (UI-C04)
- Quantity: 1–10; at 0, confirm deletion
- Total = Σ(base price + option extras) × quantity
- States: normal / empty cart / contains sold-out / save failed
- AC-1 Given empty cart When open
       Then order button disabled + reason text
- AC-2 Given contains sold-out item Then warning on that row
- Verification: TEST-006, TEST-007
HANDS-ON 0415 minSolo → pairs · rewrite

From a vague spec to a buildable spec

GoalWrite a spec with ID + rules + states + acceptance criteria that AI can't interpret however it likes
## Menu list - Menu items appear nicely - Sold-out items are shown properly
ID
REQ-009
Number rules
max · min · count
States
normal / sold out / error
Acceptance criteria
Given … Then …
- Sold-out items are shown properly

Auto-check

ID
Number rule
2+ states
Given · Then
Fill the blanks to check
0/4
Tick the boxes
to check yourself
Career linkTurning vague requests into clear requirements is core daily work for PMs and planners.
When to add a new MD

Add an MD when you see these signals

Same explanation 3 timesREPEATED PROMPTYou type "use CSS variables" or "write in English" every time→ .agents/rules/*.md
AI repeats the same mistakeREPEATED MISTAKEIt lets sold-out items into the cart, or renames status values→ Add bans and examples to rules
Same steps every timeREPEATED PROCEDUREYou manually ask for build → test → log → update trace table→ .agents/skills/*/SKILL.md
New screen · feature · policyNEW SCOPEScope not in the docs appears, like coupons, notifications or admin permissions→ service-planning/*.md + REQ ID
A decision changesCHANGED DECISIONIt now differs from the spec, like "auto-change ready for pickup → done"→ DECISION_LOG + fix the original spec
HANDS-ON 0510 minPairs · quiz

Which MD should you add for this signal?

GoalWhen you see a signal during development, decide right away which MD to add
Repeated explanationSame words 3 times→ Rule
Repeated mistakeAI got it wrong again→ Add a ban
Repeated stepsSame order every time→ Skill
New scope · decision changeNot in docs · changed→ Spec+REQ · DECISION_LOG
I keep typing "use design tokens" every time
✓ Rule — same explanation 3 times → .agents/rules/
AI let a sold-out item into the cart again
✓ Add a ban — same mistake again → ban and example in the rules
After building, I manually ask for log and trace-table updates every time
✓ Skill — same steps again → SKILL.md
Suddenly we need a coupon feature
✓ Spec+REQ — new scope → service-planning + REQ ID
We decided to change ready for pickup → done automatically
✓ DECISION_LOG — decision changed → DEC record + fix the original spec
Correct 0 / 5
0/4
Tick the boxes
to check yourself
Career linkThe habit of spotting repetition and automating it is the biggest sign of a highly productive developer.
How to add an MD · 5 steps

A new MD must go through 5 steps to become AI's standard

① Choose layerRule, spec, log or procedure? Add to an existing doc or make a new one?
② Template + IDCopy the template and give a unique ID like REQ-011 or UI-C09
③ Register in mapAdd the path to the AGENTS.md doc map and TRACEABILITY.md
④ AI cross-auditCheck for term, ID and status contradictions and gaps with existing docs
⑤ Approve · commitA person reviews and fixes, then confirms with a docs: commit
Skip ③ and the doc exists but AI doesn't know it's there. Adding means registering too.
Let AI draft, you decide

AI drafts the MD, people decide

My 5-line draftPurpose · rules · out of scope · questionsAI structures itTemplate · find blanksMark [Assumption]·[Question]Don't invent new factsA person decidesConfirm as [Decision]

1) I write 5 lines first

Purpose: first-order discount with a coupon
Users: first-time customers
Rules: once per person, minimum order ₦8,000
Out of scope: loyalty points, stacking coupons
Unknown: return the coupon if sold out?

2) Ask Antigravity to structure it

Using @AGENTS.md @service-policies.md,
write the draft above as service-planning/coupon-spec.md
in the template format (purpose · REQ · states · AC · TEST).
Don't invent new facts — mark them as [Assumption]/[Question],
and list any terms or status values that clash with existing docs.
Create the file, but don't change any code.
A person checks each [Assumption] AI marked and turns it into a [Decision] or deletes it. A doc with unchecked assumptions is not yet a contract.
Antigravity build loop

Build in a plan → review → run → verify loop

/planWrite planReview planComment · approveProceedBuildWalkthroughCheck in browserAI_WORK_LOGRecord judgmentgit commitSmall commit↻ Repeat the same loop for the next REQ
/planExplore and ask without changing code, then write a plan artifactNo coding right away
Review planCheck referenced doc paths, files to change and scope; fix with commentsHuman approval point
Run · verifyBuild step by step, then check behavior for each acceptance criterion (AC)0 console errors
Record · commitLog accept/change/reject judgments and make a small commitA unit you can roll back
Build contract prompt

A build request is a contract that locks scope

Request without scope

Build the cart feature
and do the admin screen too.
Make the design pretty.
  • Rewrites many files at once
  • Adds features not in the docs
  • Can't review what changed

Doc-contract request

/plan
Use only the approved MDs in service-planning and service-analysis
as the basis for building.
This scope is only REQ-004 (UI-C04).
Before writing code, first report the related doc paths, files to change
and anything unclear.
After building, summarize the changed files, how to run it
and results for each AC.
HANDS-ON 0620 minSolo · Antigravity

Write a /plan request and review the plan

GoalWrite a /plan request that locks scope, and review AI's plan before approving
1
Pick a REQJust one scope
2
@mention docsOnly the MDs you need
3
Run /planPlan without changing code
4
Review planProceed after 5 checks
WarningIf you press Proceed without reading the plan, files outside the scope may change.

/plan prompt

Review the Implementation Plan

0 / 5
0/4
Tick the boxes
to check yourself
Career linkThe habit of "review the plan before building" is the most trusted attitude in real projects where mistakes are costly.
Vertical slices · 3 cycles

Don't build it all at once — slice it vertically

Cycle 1 · Customer mobileBrowse menu → choose options → cart → order complete (360–430px)@customer-order/*.md
Cycle 2 · Admin PCSee new orders → details → change status (received→cooking→ready→done) → manage sold-out (1280px+)@admin/*.md
Cycle 3 · Exceptions · recoveryRequired option not chosen, sold-out blocking, empty cart, retry after save failure@service-policies.md @test-data.md
✗ Horizontal slicingScreen UI · all empty shellsLogic · rules · none yetData · none yetLots of screens, but you can't actually order✓ Vertical slicing (vertical slice)Screen UILogic · rulesDataCycle 1Customer orderCycle 2AdminCycle 3Exceptions · recoveryToday's goal: finish one end to end
Doc drift warning

Change only the code, and the next AI trusts the old docs

✗ Changing only the codeChange codeDocs stay oldNext AI trusts the docsReverts the codeSame problem keeps repeating

✓ The right order — docs first, code last

① RecordLog the difference and reason in DECISION_LOG as DEC-###
② ImpactHave AI find the related REQ · UI · DATA · API · TEST
③ Fix docsFix the original service-planning spec first
④ ApproveStudents or the team review and approve the change
⑤ Code · re-verifyThen change the code and re-run tests
Put these 5 steps in the doc-contract.md rule, and when something different from the docs is needed, AI will stop and ask first.
HANDS-ON 0710 minPairs · put in order

When you want to build it differently from the docs, what's the right order?

GoalWhen a change is needed during building, keep the order docs → approval → code
SituationWhile building REQ-012, changing "ready for pickup → done" automatically looks better. But the spec says the admin changes it by hand.
1
Read cards5 step cards
2
Talk with partnerWhat comes first?
3
Tap in orderSlots fill up
4
Check answerWhen is code?

① Tap the cards in order

② The order I chose

1…
2…
3…
4…
5…
0 / 5 chosen
0/4
Tick the boxes
to check yourself
Career linkDevelopers who follow change-management steps are especially trusted in large organizations and government projects.
Skills · reusable procedures

Turn repeated steps into SKILL.md and /call them

.agents/skills/build-req/SKILL.md

---
name: build-req
description: Use when building one requirement ID according to the doc contract.
  Applies to "build REQ-xxx" and "/build-req" requests.
---
1. Find the REQ's UI·DATA·API·TEST paths in TRACEABILITY.md
2. Read only the related MDs and ask about unclear points first
3. Write an Implementation Plan and wait for approval
4. Build the minimum scope and check each AC
5. Add one line to AI_WORK_LOG.md and update the trace table status

Rules vs Skills

STOPRules = signs1.2.3.4.Skills = recipe cardsAlways visible, shortTaken out when needed
  • Rules: principles to always follow (short)
  • Skills: step-by-step recipes for a task (loaded only when needed)
  • The more specific the description, the more accurately AI uses it at the right time
  • Call directly in chat with /build-req REQ-004

The old Workflows (.agents/workflows) are being merged into Skills. If you make a new one, write it as a Skill.

Log & verify

Leave records and evidence before declaring it done

AI_WORK_LOG.md (1 request = 1 line)

| AI ID  | REQ     | Request          | Result           | Human fix              | Decision         |
| AI-001 | REQ-004 | Total calc       | TEST-006 passed  | Added negative-qty guard | Accepted w/ change |
| AI-002 | REQ-004 | Quantity button UI | Changed colors on its own | Restored design tokens | Rejected, re-requested |

Feature done check

  • Every AC can be reproduced in the browser
  • 0 console (F12) errors
  • 360px mobile / 1280px PC layouts work
  • Field names and status values in the spec = variable names in the code
  • Update TRACEABILITY status to "Built"
  • Clear commit message: feat(REQ-004): ...
HANDS-ON 0810 minSolo · record

Write one line of AI_WORK_LOG yourself

GoalFor every AI task, record request · result · human fix · decision in one line
| AI ID  | REQ     | Request          | Result           | Human fix              | Decision         |
| AI-001 | REQ-004 | Total calc       | TEST-006 passed  | Added negative-qty guard | Accepted w/ change |
| AI-002 | REQ-004 | Quantity button UI | Changed colors on its own | Restored design tokens | Rejected, re-requested |
1
1 AI requestWhat did you ask?
2
Check resultTests · screen
3
Human fixWhat did you fix?
4
Record judgmentAccept · change · reject

One line of AI_WORK_LOG.md

Please fill the 5 boxes
0/4
Tick the boxes
to check yourself
Career linkA record of working with AI is evidence that you're "a developer who handles AI well" — use it right away in your portfolio and interviews.
Day 4 mission

Today's Outputs

Output 1 · Rule MD
AGENTS.md (6 blocks) + 2+ .agents/rules (different triggers)
Output 2 · Extra spec MD
Add 1+ MD from a signal found during development + register in map and trace table
Output 3 · Working REQ
Finish 1 vertical feature with /plan → review → build
Output 4 · Records
3+ AI_WORK_LOG entries (1+ changed or rejected) · TRACEABILITY updated
  • Write your draft and questions before opening AI
  • Don't put real personal data, payment data or API keys in MDs or code
  • Don't copy outside brand logos, text or images
  • People must be able to read and explain the MDs and code AI made
Takeaway

Prompts disappear,
MDs remain.

The person who gets AI to work well is not the one who asks more, but the one who designs good standards for AI to read and judges results by them.

promptpromptpromptpromptpromptPrompts disappearAGENTS.mdspec.mdDECISION_LOGThe next AI reads it tooMDs remain
Power to designMake rule, spec, log and procedure MDs in the right layer
Power to lockLock scope one requirement ID at a time and review the plan
Responsibility to judgeAccept, change or reject by the docs, and record it
1 / 31
LECTURE NOTE

Hands-on Lab

Today's Lab Flow

See the example project, mission guide and grading rubric in the Document-Driven Service Development PBL Workspace. The templates below match that example structure (service-planning · analysis · implementation · validation).

STEP 01 · 30 min

Set up rule MDs

Create AGENTS.md in the root and fill in the doc map, then put 2 rules with different triggers in .agents/rules.

AGENTS.md · rules/
STEP 02 · 40 min

Spec audit & add MDs

Use /doc-audit to find contradictions and gaps in existing specs, and add the MDs you need following the 5-step process.

REPORT_DOC_AUDIT · new MD
STEP 03 · 90 min

Build one REQ vertically

Get a plan with /plan, fix the scope with comments, then Proceed. Check each AC in the browser.

/build-req REQ-___
STEP 04 · 40 min · Key

Record · trace · retro

Record change/reject judgments in AI_WORK_LOG and update TRACEABILITY. Anything that differs from the docs goes to DECISION_LOG.

AI-### · DEC-### · TRACE

Project MD Map — what AI reads, and when

Based on the example project. "Auto" means places Antigravity reads by itself; "manual" means places it reads only when told via the AGENTS.md doc map or an @mention.

FileLayer · roleWhen AI reads itWhen to create and update
AGENTS.mdRule · project constitution and doc mapAuto · always, every chatWrite at the start of Day 4 · update the map whenever you add an MD
.agents/rules/doc-contract.mdRule · docs-first principle, change processAuto · always_onAdd bans and examples when AI makes the mistake of ignoring docs
.agents/rules/frontend-style.mdRule · design tokens, responsive, accessibilityAuto · glob (when working on CSS/HTML files)After the design concept is set · when color or spacing rules change
.agents/rules/safety.mdRule · personal data, payment and copyright boundariesAuto · model_decisionBefore starting data, analytics or payment features
.agents/skills/build-req/SKILL.mdProcedure · recipe for building per REQWhen intent matches, or /build-reqWhen you've repeated a build-request prompt twice or more
.agents/skills/doc-audit/SKILL.mdProcedure · doc cross-auditWhen intent matches, or /doc-auditRight after adding an MD or changing a spec
service-planning/**/*.mdSpec · screens, flows, policy, design, dataManual · read via doc map, @mention, or skill pathsWritten in Mission 2 · add with REQ IDs when new scope appears
service-analysis/*.mdSpec · metrics, events, analytics APIManualBefore building REQs that need event tracking
TRACEABILITY.mdLog · REQ→UI→DATA→API→TEST chainManual · read in step 1 of the build-req skillAdd a row when adding an MD · change status after building and verifying a REQ
DECISION_LOG.mdLog · decisions and reasons for changeManual · doc mapWhen scope or policy changes, or when an AI suggestion is rejected
service-implementation/AI_WORK_LOG.mdLog · 1 AI request = 1 lineManualEvery time an AI build request finishes

MD Template Kit — copy and use right away

Copy each block with its Copy button and save it as a file at the path shown. Change the [bracketed] parts for your team project.

Rule · root

AGENTS.md

Put it in the project root. Always applied, with no frontmatter.

# [Service name] — AGENTS.md

## 1. One-line definition
[Customers] [order sandwiches and drinks] on [mobile],
and [the admin] manages [order status and sold-out items] on [PC].

## 2. Doc map (question → doc to read)
- Scope · decisions → PROJECT_BRIEF.md, DECISION_LOG.md
- Customer screens · flows → service-planning/customer-order/*.md
- Admin screens → service-planning/admin/*.md
- Shared policy · order status values → service-planning/common/service-policies.md
- Design → service-planning/design-concept.md
- Metrics · events → service-analysis/*.md
- Verification · test data → service-validation/*.md
- ID links → TRACEABILITY.md

## 3. Tech stack · run
- HTML/CSS/Vanilla JS, no build step
- Run: npx serve service-implementation
- Shared data: service-implementation/shared/store.js

## 4. Way of working
- Handle only one requirement ID at a time.
- Before changing code, first report related doc paths, files to change and unclear points.
- If something different from the docs is needed, don't change the code — propose a doc change first.
- When finished, add one line to AI_WORK_LOG.md.

## 5. Don'ts
- Don't add features, screens or fields not in the docs.
- Don't store real personal data, payment data or API keys.
- Don't copy outside brands' logos, text or images.

## 6. Definition of done
- All acceptance criteria (AC) for the REQ are confirmed in the browser
- 0 console errors, works on 360px mobile / 1280px PC
- TRACEABILITY.md status updated
Rule · always_on

.agents/rules/doc-contract.md

Docs-first principle. Keep only short, absolute rules as always_on.

---
trigger: always_on
description: Docs-first contract principle and spec change process
---
# Doc Contract Rules

- The only basis for building is the approved MDs in service-planning and service-analysis.
- If a request has no requirement ID, first ask which REQ it is.
- Don't guess values not in the spec; report them as [Question].
- Use the spec's field names and status values as-is in the code.
  (e.g. received / preparing / ready / completed / canceled)

## When something different from the docs is needed
1. Stop without changing code.
2. Propose the difference and reason as a DECISION_LOG.md draft (DEC-###).
3. Show the list of affected REQ·UI·DATA·API·TEST.
4. After human approval, change in the order docs → code.
Rule · glob

.agents/rules/frontend-style.md

Applied automatically only when handling CSS/HTML files.

---
trigger: glob
globs: **/*.css, **/*.html
description: Design token, responsive and accessibility rules
---
# Frontend Style Rules

- Use only the CSS variables in design-concept.md for colors, spacing and fonts.
  Don't write new color values directly.
- Mobile 360px first; the PC admin uses 1280px.
- Buttons at least 44px tall, main actions in thumb reach.
- Show states (sold out · error · required) with color + icon + text together.
- A label for every input, an aria-label for icon buttons.
- Don't skip loading, empty, error and success states.
Procedure · Skill

.agents/skills/build-req/SKILL.md

Call it in chat with /build-req REQ-004.

---
name: build-req
description: Use when building one requirement ID according to the doc contract. Applies to "build REQ-xxx", "build this feature" and "/build-req" requests.
---
# Per-requirement build procedure

1. In TRACEABILITY.md, find the target REQ's UI·DATA·API·TEST IDs and doc paths.
2. Read only those docs. Report unclear points first as a [Question] list.
3. Write an Implementation Plan.
   - Referenced doc paths / files to change or create / how to check each AC
   - Don't change files before human approval.
4. After approval, build the minimum scope. No refactoring outside scope.
5. Summarize in a table what you confirmed in the browser for each AC.
6. Add one line to service-implementation/AI_WORK_LOG.md.
7. Change that row's status in TRACEABILITY.md to "Built".
8. Suggest a commit message: feat(REQ-xxx): [summary]
Procedure · Skill

.agents/skills/doc-audit/SKILL.md

Run /doc-audit right after adding an MD or changing a spec.

---
name: doc-audit
description: Use to cross-review planning, analysis and verification MDs for contradictions and gaps. Applies to "audit docs", "check specs" and "/doc-audit" requests.
---
# Doc cross-audit procedure

Don't add new requirements or edit docs — only find problems.

1. Read every MD in the AGENTS.md doc map.
2. Report the following in a table:
   - Mismatched terms · IDs · order status values between docs
   - Features in screen specs with no DATA/API definition
   - REQs missing from TRACEABILITY.md, or REQs with no TEST
   - Done criteria that can't be measured ("convenient", "fast")
   - Privacy · payment · permission · copyright risks and questions people must decide
3. Propose the result as a draft of service-validation/REPORT_DOC_AUDIT.md.
Spec · new MD

New feature spec template

Add it under service-planning/ when new scope appears.

# [Feature name] Spec — REQ-0__

- Status: draft / in review / approved
- Author: [name]  ·  Approver: [name]  ·  Related DEC: DEC-___

## 1. Purpose
[Who] uses this feature [in what situation] [to do what].

## 2. Scope
- In:
- Out:

## 3. Screens (UI-___)
| Element | Info shown | User action | Next state |
|---|---|---|---|

## 4. Rules · data (DATA-___)
- [field]: [type], [allowed range], [default]

## 5. States
- Normal / loading / empty / error / recovery

## 6. API · events
- API-___ :  ·  EVT-___ :

## 7. Acceptance criteria
- AC-1 Given [condition] When [action] Then [result]
- AC-2

## 8. Verification
- TEST-___ (service-validation/...)

## 9. Open questions
- [question]
Log

DECISION_LOG · AI_WORK_LOG · TRACEABILITY

Headers and first-row examples for three files. Save only the parts you need, separately.

# DECISION_LOG.md
| DEC ID | Date | Decision | Reason · evidence | Affected IDs | Approved by |
|---|---|---|---|---|---|
| DEC-001 | 2026-11-19 | Auto-complete 30 min after ready for pickup | Prevent admin misses | REQ-007, TEST-012 | Team |

# service-implementation/AI_WORK_LOG.md
| AI ID | REQ | Request | Suggestion received | Result | Human fix | Decision · reason |
|---|---|---|---|---|---|---|
| AI-001 | REQ-004 | Cart total | Sum function | TEST-006 passed | Negative-qty guard | Accepted after change |

# TRACEABILITY.md
| REQ | UI | DATA | API · EVT | TEST | Doc | Status |
|---|---|---|---|---|---|---|
| REQ-004 | UI-C04 | DATA-cart | API-003, EVT-cart_added | TEST-006 | customer-order/order-flow.md | Built |
prompt

Antigravity Practical Prompt Collection

Paste and use as-is for each situation. @ is a file mention.

[1] First project setup
Read this repo's folders and MDs and create an AGENTS.md draft
in the 6-block format (definition · doc map · stack · way of working · don'ts · definition of done).
Mark anything uncertain as [Question]. Don't change any code.

[2] Add a new MD
Using @AGENTS.md @service-policies.md, write the draft below as
service-planning/[filename].md in the 'new feature spec template' format.
Don't invent new facts — mark them as [Assumption]/[Question],
and propose the rows to add to the AGENTS.md doc map and TRACEABILITY.md.

[3] Build plan
/plan I want to build REQ-___. Use only approved MDs as the basis,
and include referenced doc paths, files to change, unclear points and how to check each AC in the plan.

[4] Error analysis
Analyze the console error below. Explain possible causes first,
and suggest only a minimal fix within the REQ-___ scope. [paste the full error]

[5] Doc–code match check
For each "Built" REQ in @TRACEABILITY.md, compare in a table whether
the spec's field names and status values match the real code variable names. Don't change anything.

[6] Retro
Read this cycle's AI_WORK_LOG and summarize: what AI did quickly / what it missed /
what people fixed / what to add to the rule MDs next time.

10-Day Course Navigation

Click the buttons above to go to the Day 1–10 learning pages.

Learning Workspace

Antigravity · Doc-Driven Development Videos & Day 4 AI Helper

Pick a reference video by topic on the left, and ask the AI chat on the right about using MDs and the Antigravity build lab.

Related YouTube VideosDay 4 recommended materials
  • Antigravity basics
  • 1. Google Antigravity 2.0: intro, install and how to useKorean intro from install to using agents KR
  • 2. Antigravity 2.0 × IDE × CLI: complete install + basics guideIDE and CLI setup, basic workflow KR
  • 3. Build and deploy your own site with AntigravityFull process: request → build → check → deploy KR
  • 4. Google Cloud Live: Getting started with AntigravityOfficial Google Cloud live · agents and artifacts EN
  • 5. Google Antigravity, Explained: The Agent-First IDEAgent Manager · Editor · plan/review structure explained EN
  • Rules · Skills MD
  • 6. Google Antigravity Rules & Workflows SIMPLIFIED!How to make rule MDs and repeated-procedure MDs EN
  • 7. Google Antigravity Rules, Knowledge & The Agent ManagerHow rules and knowledge shape agent work EN
  • 8. How to Create Agent Skills in Google Antigravity (2026)Writing SKILL.md and slash calls EN
  • 9. Harness Engineering — applying skills to AntigravityLocking agent work quality with skill MDs KR
  • Doc (spec)-driven development
  • 10. Stop coding by hand — just give instructions! Antigravity in practice & SDDUsing Antigravity with spec-driven development (SDD) KR
  • 11. Specs Driven Development with Antigravity IDE and AGENTS.mdLocking build scope with AGENTS.md and spec docs EN
  • 12. Hands-On Spec-Driven Development with SpecKit and AntigravityLab: spec → plan → tasks → build EN
  • 13. Spec-Driven Development Explained: The Workflow That Keeps AI Agents AlignedWhy docs keep AI agents aligned EN
  • 14. From vibe coding to rigor: Spec-driven development with AI at scaleFrom vibe coding to spec-based development EN
  • 15. Spec-Driven Development with AI Agents — Anton ArhipovFrom high-level requirements to working software EN
  • API reference (earlier Day 4 videos)
  • 16. APIs for Beginners - TwilioBasics before writing API_CONTRACT.md EN
  • 17. Full HTTP Networking & REST API CourseUnderstanding requests, responses and error codes EN
  • 18. System Design Concepts and API DesignReference for structure and API design EN
  • 19. REST API Design best practicesQuality standards for API spec MDs EN

Videos are embedded public YouTube videos. If playback is restricted by the uploader, open them directly on YouTube. Antigravity updates often, so menus and paths in videos may differ from the current version.

Day 4 · Daily Feedback

Today's Course Satisfaction Survey

After Day 4 class, please answer a short survey. Your answers help us improve the next class and the course.

Open Day 4 SurveyJoin with the button or QR code
Day 4 Daily Feedback Survey QR codeSCAN TO OPENNigeria AI Training · Day 4