Required reading before starting
Before making any judgment or taking any action, first run the CodeStable preflight: read .codestable/attention.md; if missing, first cs-onboard; do not substitute by reading external AI entry points (see .codestable/reference/execution-conventions.md）。
When the user asks you to do a small feature, AI would normally just start working anyway—this skilldoes not change that. It only does one thing: before you start, it points you to the CodeStable knowledge already accumulated in the project, so a quick search gives the code you write one more layer of protection than writing it bare; after you finish, write back aminimal {slug}-ff-note.md so this work is traceable, visible to cs-req / cs-domain backfill, and can be included in scoped-commit commits.
Very light: no design doc / checklist / acceptance list / pre-work user confirmation. Read the guidance, read the code you need to read, write the code you need to write, and write back a paragraph when done.
Before starting, take a quick look at .codestable/
Glob .codestable/ discover available directories and documents, and use them as needed:
requirements/CONTEXT.md— domain terminology; name things using project terminology, do not invent namesrequirements/adrs/— settled architecture decisions; before changing cross-module things, grep related adr to avoid violating themcompound/— accumulated pitfalls / tips / research:grep -r "关键词" .codestable/compound/requirements/{slug}.md— when there is a related req, read the boundariesfeatures/— when there is a similar feature, refer to its designreference/— shared-conventions.md / tools.md
How to use
Before starting, ask 2 questions:
- Has anyone stumbled over this code before? →
grep -r "关键词" .codestable/compound/ - Does this code have any already-settled implementation constraints? → look at
requirements/adrs/related ADR + grepcompound/to find implementation precedents
If you get a hit, fold the conclusion into the implementation (write according to the constraints, not copy). If you get no hit, writing by your own judgment is perfectly normal. If you cannot find anything, try a few other keywords.
Execution gate (worktree + commit)
fastforward directly modifies project source code and is the end of the fast track, but the two gates still must be run. If the slug is not yet decided, first settle it based on the action (see "auto-generate slug" below), and use the unit path .codestable/features/YYYY-MM-DD-{slug}。
Before starting, run the start gate:
python3 .codestable/tools/codestable-worktree-gate.py --root . --json start --unit .codestable/features/YYYY-MM-DD-{slug}
If the gate does not pass, do not start changing code; when the user approves an override, first write in the unit directory worktree-override.md（reason / scope / approval）。
Before ff-note is written to disk and before the wrap-up commit, run the commit gate:
python3 .codestable/tools/codestable-worktree-gate.py --root . --json commit --unit .codestable/features/YYYY-MM-DD-{slug}
If the gate does not pass, handle the findings first, and do not treat "verification passed" as done. For installation of the gate tool and the branch-guard hook explanation, see .codestable/reference/branch-guard-hooks.md。
Hold to these while writing code
The hard constraints of design / implement in a streamlined form for fastforward. No design doc does not mean you can ignore them—these keep you, when "going straight to work", from drifting toward the pitfalls AI defaults to stepping into.
Think "where it goes" before writing
Answer in 30 seconds:In the project structure, where does what you are adding this time belong?
- Should an existing module already be responsible for it? → extend there, do not create something new
- Does it span multiple modules? → extract a common layer / let one side lead
- Do existing modules call it something different? → grep synonyms
- Is it unlike anything existing? → it probably should switch back to the full design process
Default pitfall:Without thinking, adding it to the most convenient file in front of you—once added, it becomes a "basket that holds everything".
Take a quick look at the current state of the files you are about to change
Before you start writing, take a look: How long is the file? How many things is it responsible for? How many methods does the class have? Is what you're adding a natural extension or is it pushing it toward "can do everything"?
If it's healthy, just add directly; if it needs to be tidied up first (split long files / extract heavy functions), thentidy up first, then add, with the scope locked to "only move, don't change behavior"; for structural problems (redivision of responsibilities / splitting or merging modules) → stop and go back to the design process.
By default, write the least amount of code
Only write what the user explicitly asked for. Don't conveniently add:
- configuration options / parameter toggles / abstraction layers / interfaces / factories for "might be needed later"
- defensive fallbacks / try-catch that nobody asked for
- edge-case handling the user didn't mention
Criterion: after writing, if you feel "do I still need to add X"—can the user perceive X? If not, don't add it. Extra code isn't neutral; it's a maintenance burden for those who come after.
Only touch what should be touched
Only change the functions that need changing. Other functions in the same file are ugly / oddly named—unless they conflict with this change, don't touch them. New code style should match the existing style in the current file. If you see something elsewhere worth changing → "Incidentally noticed: {file:line number} {problem}, not in this scope" and let the user decide.
New logic goes in a new file by default
If it will be referenced elsewhere → new file; if it's a small utility function used in only one place → put it nearby.
Don't write patch branches
If if (特殊情况) { 特殊处理 } → Stoppops up. This kind of branch is basically only because the approach didn't cover this case, and forcing it through gets you "special logic added just to make the code run". Either change the data structure so it doesn't need special handling, or explicitly acknowledge it's an edge case and comment on why it's special.
Reflex signals to stop when triggered
- Appending to a file > 300 lines / adding a method to a class with > 10 methods
- A function doing more and more, exceeding one screen
- Writing a second block of code that's "basically the same as the block above with two variables changed"
- Function parameters reaching the 4th
- Piling things into
utils.ts/helpers.tsthe all-purpose util - When introducing a new concept name, first grep for the same / similar names
For the complete checklist, see .codestable/reference/shared-conventions.md Section 7.
After writing, backfill {slug}-ff-note.md
Only do this step afterthe code is written, verified, and the user has confirmed the result is OK—creating an empty shell beforehand will break ff's lightweight feel.
Auto-generate the slug
Don't ask the user. Rules:
- Extract 2-4 English kebab-case words from the user's initial request to summarize the action / object (e.g. "rename-cwd-helper", "add-export-button", "fix-toolbar-layout")
- Don't extract business noun abbreviations, don't transliterate Chinese, keep lowercase with hyphens
- If unsure, be a bit conservative: "tweak-{object}" / "small-{action}" is also better than forcing precision
Final path:.codestable/features/YYYY-MM-DD-{slug}/{slug}-ff-note.md, with today's date.
Template
---
doc_type: feature-ff-note
feature: {slug}
date: YYYY-MM-DD
requirement: {req-slug 或留空}
tags: [...]
---
## 做了什么
{1-3 句：解决什么需求 / 加了什么能力，业务视角}
## 改了哪些
- {file:行号区间或函数名} — {一句话说改了什么}
- ...
## 怎么验证的
{1-2 句：跑了哪些验证 / 浏览器走通了哪条路径 / 跑了什么测试}
## 顺手发现（可选，不阻塞）
- {文件:行号} {问题简述} — 不在本次范围
Write it really lightweight: each section is just a few lines, don't write it as a mini design / mini acceptance. The goal of this document is "half a year later, someone looking at the git log can jump in and understand in 30 seconds what was done", not to replace the standard process.
After saving to disk, tell the user: "Written {slug}-ff-note.md, this fastforward closed loop."
What not to do
- Don't write a design doc / checklist / acceptance——This is the point of fastforward. If you want to write, go
cs-feat-design - Do not confirm the plan with the user——when users ask you to build a small feature, they don't want to wait for you to hold a meeting
- Do not leave
.codestable/inside{slug}-ff-note.mdany new files outside of it——unless you discover a pitfall / technique worth preserving, then start a separate conversation and usecs-keepto write it
When to break out of fastforward
If you hit any of the following situations midway through,stop and tell the user "this is more complex than expected, suggest switching back to the full process"：
- The change involves more than 3 subsystems
- New terminology needs to be introduced or conflicts with existing terminology
- The established module boundary ADR of
.codestable/requirements/adrs/needs to be broken - The user's added requirements double the scope
How to switch back: trigger cs-feat-design. Code already written just needs to be marked "partially implemented" in design.
Exit conditions
- Code is finished and the user confirms the result is OK
-
{slug}-ff-note.mdHas been persisted and all four sections are filled in (things conveniently discovered can be omitted) - There are no unaligned "incidental discoveries" (all go into the last section of ff-note, left for later)
Wrap-up commit
Execute according to the "scoped-commit" rules in section 4 of .codestable/reference/shared-conventions.md . For this channel:
- Commit scope: this round's code changes +
{slug}-ff-note.md - After ff-note is persisted, tell the user "ready, should I commit on your behalf?" and execute only after the user explicitly agrees
Before the wrap-up commit, first enter cs-code-review to do a round of independent diff review; do not proceed to commit until Critical / Important are cleared; the right to initiate scoped-commit belongs to cs-code-review。
According to the recommended wrap-up order for "feature-ff" in section 3 of shared-conventions.md , prompt each item in one sentence (if the user says "no need", skip immediately):
- Exposed pitfalls or finalized long-term constraints → "preserve to compound? (
cs-keep）" - Finally ask whether to perform scoped-commit on the user's behalf
Easy pitfalls
- Skipping knowledge retrieval entirely and just writing——the only reason for this skill is to make you search before writing
- Treating the found learning / decision as "reference" rather than "constraint"——a decision has been finalized; violating it means either making a new decision or not doing it
- Starting to write a design doc——fastforward means not writing design
- Discovering the task has become complex but still forcing it through fastforward——the cost of switching back is far lower than changing all the way to the end with a wrong plan
- Creating an empty ff-note shell before starting work——this breaks fastforward's lightweight feel; you must finish code + verification before writing back
- Writing ff-note as a mini design / mini acceptance——the four sections together only need a dozen or so lines; more than that means this should not go through fastforward
- Skipping ff-note and committing directly——same reason as issue-ff mandatory fix-note: without records, later people cannot trace it