How to draft or refresh the two thin AI-facing files — the AI Architecture Context and the AI Coding Guidelines: provenance header, rule shape, weighting, the ordered section lists, and what to exclude. Use while writing either file in bootstrap or guidance-update. Pairs with assess-coverage (what to cover); this skill is how to write it.
Installation
Installer avec Codex ou Claude Copiez ce prompt, collez-le dans Codex, Claude ou un autre assistant, puis laissez-le vérifier la page du skill et l'installer pour vous.
How to draft or refresh the two thin AI-facing files — the AI Architecture Context and the AI Coding Guidelines: provenance header, rule shape, weighting, the ordered section lists, and what to exclude. Use while writing either file in bootstrap or guidance-update. Pairs with assess-coverage (what to cover); this skill is how to write it.
Inputs
target-file — which file to draft or refresh: the AI Architecture Context (ai-context.md) or the AI Coding Guidelines (ai-coding-guidelines.md).
coverage-decisions — the final rules from assess-coverage (concerns an approved source settles). Open decisions are not drafted here — they go to the clarifications ledger.
sources — the resolved source list from the source map (read-context-manifest): SAD, ADRs, specs, diagrams, and canonical in-repo examples, each with its authority and path to link.
Procedure
Use conventional, stable headings. Do not reinvent the structure.
Write short declarative bullets, not prose.
Link to sources, do not copy them.
Shape each rule as one line: the imperative rule, a link to the source that owns the full detail, and an inline ask-first if … trigger. Point to a canonical in-repo example ("mirror this") when one exists. State each rule once and cross-link; do not restate.
Make weight visible: mark non-negotiables as Never/Always and preferences as Prefer.
Open each file with its provenance header (one line):
Context: generated & maintained by the toolkit; mirrors (never overrides) the sources in the source map; evolve via ai-guidance-update.
Guidelines: generated & maintained by the toolkit; applies the Architecture Context in code (doesn't redefine it); evolve via ai-guidance-update.
Follow the Output section order as a baseline, not a ceiling. Write only sections with real content; omit concerns that don't apply; never pad. Keep the listed sections in their given relative order; append any added section after the listed ones (or in the nearest topical position), never reordering the listed set.
Add a section for any repo- or domain-specific concern that matters even if it isn't listed (e.g. multi-tenancy, performance/SLAs, i18n), kept concrete and repo-specific, not generic advice.
Cover every relevant concern, but shrink to a pointer where an artifact already covers one well. Thin does not mean narrow.
Keep the file clean and final. Write only decided rules, ready for downstream use. Exclude all plumbing — statuses, placeholders, TBD/proposed markers, and open decisions (those live in the clarifications ledger, never here) — and full SAD content, long ADR rationale, large copied diagrams, implementation plans, story-specific detail, unapproved decisions, generic engineering advice.
Output
ai-context.md — sections in this order:
Purpose & scope — covered areas
Read order & authority order
Must-read sources — pointer to the source map (no prose source list)
