# F Stack Dev Rule

> F-Stack Mandatory Development Rules

- Skill: `f-stack/f-stack-dev-rule` (Agent Skill, multi-file: 4 files)
- Install (CLI): `npx skillmds@latest add f-stack/f-stack-dev-rule`
- Raw SKILL.md: https://api.skillmd.com/api/skills/f-stack/f-stack-dev-rule/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: f-stack (https://skillmd.com/u/f-stack)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/f-stack/f-stack-dev-rule

---


# F-Stack Mandatory Development Rules

This skill is a collection of mandatory rules for all development tasks in the /data/workspace/f-stack workspace. Violating any of them causes the task to be bounced back for correction. Zero tolerance.

## 1. Shell Operation Script Rules

Direct invocation of rm / kill / chmod command families is forbidden. Always use the scripts bundled with this skill (under the `scripts/` subdirectory of this skill's directory; resolve them as absolute paths against the skill base directory provided at load time):

### 1.1 Delete files -> scripts/rm_tmp_file.sh

- Single file: `scripts/rm_tmp_file.sh /full/path/to/file`
- Multiple files: `scripts/rm_tmp_file.sh /path/a /path/b`
- Directory: `scripts/rm_tmp_file.sh /full/path/to/dir`
- Trash location: `/tmp/.trash` (keeps the path prefix for traceability)
- Permanent purge: `scripts/rm_tmp_file.sh --purge <trash_path> [--older-than Nd] [--dry-run]` (purge whitelist is only /tmp/.trash, /data/.Trash-0/files, /data/.Trash-0/info)
- Forbidden: direct `rm`, `rm -rf`, `find -delete`, or embedding rm inside bash snippets
- Bulk deletion of *.o etc.: first collect absolute paths with `ls`/`find`, then pass them all to the script at once

### 1.2 Stop processes -> scripts/kill_process.sh

- Single PID: `scripts/kill_process.sh <pid>`
- Multiple PIDs: `scripts/kill_process.sh <pid1> <pid2>`
- Forbidden: `kill`, `pkill`, `killall`, `kill -9`, `pgrep | xargs kill`, kill embedded in trap/cleanup, or any other form

### 1.3 Change permissions -> scripts/chmod_modify.sh

- Usage: `scripts/chmod_modify.sh <mode> <path1> <path2> ...` (mode is compatible with chmod(1), octal or symbolic)
- Forbidden: direct `chmod`, `chmod -R`, `install -m`, `setfacl`, or any other form
- Note: the script snapshots pre-change permissions to /tmp/.trash/, audits to /tmp/.chmod_audit.log, refuses high-risk paths, and warns on setuid/setgid bits

### 1.4 General rules

- make clean / make install and other build-system targets are build tool operations and may run directly
- If a script lacks a needed feature (e.g. --reference=), extend the script first, then use it; no temporary bypasses allowed

## 2. Build Rules

- After modifying any .c/.h file, run `make clean` (or an equivalent full-clean target) before a full rebuild; incremental builds are forbidden
- Header changes affect every translation unit that includes them; clean is required even for a single-file change
- Build verification is only valid with a clean build; a passing incremental build is not evidence
- After modifying a common header, verify every file that includes it still compiles; a full make with no errors is required before a PR
- Two known local build pitfalls and their workarounds:
  - The IDE-injected safe-delete hook blocks the rm inside make clean: use `PATH="/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/root/bin" make clean`
  - `make -j16` races with machine_includes: run `make machine_includes` first, then `make -j16`
- Baseline reference: lib builds with error 0 / warning 51 (existing baseline; new changes must not add warnings)

## 3. config.ini Rules

- For config.ini and similar committed config files, only changes directly related to the current feature may be committed
- Never commit local test/debug environment tweaks: lcore_mask, vlan_filter, idle_sleep, real local IPs in [portN], temporary perf-tuning values, etc.
- Always review `git diff` item by item before `git add config.ini`
- Never restore local test values with `git checkout config.ini` (local config is required for local runs and must be kept)
- Correct approach: do not select config.ini in git add; leave local test values in the unstaged area

## 4. No Real IPs in Docs

- Never record real IPs of the local runtime environment in any document (docs, README, spec, test reports, execution logs, commit messages, PR comments, etc.)
- Use descriptive placeholders: `<DPDK_NIC_IP>`, `<DPDK_NIC_IPV6>`, `<KERNEL_NIC_IP>`, `<CLIENT_IP>`, `<CLIENT_IPV6>`, `<GATEWAY_IP>`, `<GATEWAY_IPV6>`, `<BROADCAST_IP>`, `<NETWORK_PREFIX>`, `<VIP_IPV6>`, `<BACKEND_IPV6>`, etc.
- Generic forms (e.g. 9.134.x) are allowed; complete real addresses are forbidden
- `127.0.0.1` and `fe80::` link-local addresses may be written

## 5. Commit Rules

- Commit messages are always in English, 1-3 short sentences, no long essays
- Local config.ini test values must not be committed (see section 3)
- Fixing an accidental commit uses forward-fix (a new commit to roll back), never rewriting history

## 6. Code Comment Language Rules

- F-Stack project (/data/workspace/f-stack, including all code files under lib/, freebsd/, example/, tests/, etc.): comments and git commit messages must use short English; Chinese is forbidden
- Documentation files (docs/*.md, Chinese spec docs) are exempt and follow the required document language

## 7. Minimal Comments in lib/

- Only add comments where truly necessary: public interface contracts (e.g. ff_api.h), config item meanings (e.g. config.ini), and genuinely complex/non-obvious algorithms or edge handling
- Never comment self-evident code (simple assignments, obvious branches, self-explanatory calls)
- Even for complex logic, keep comments concise; prefer clear naming and structure for self-explanatory code

## 8. Multi-Agent Collaboration Rules

Applies to harness-engineering + multi-agent (agent team / spec-driven) tasks:

- **Leader must not exit early**: the leader must not end the task before every sub-agent reports its final result; actively poll and wait
- **Sub-agent timeout detection**: no unbounded waiting; side-channel probing (reading written files, git status, artifacts) takes priority over message probing
- **Write/review separation**: writing code/docs and reviewing must be done by different agents; the leader must never write and review its own work; pure research/probing/summarizing single-role tasks may be done by the leader
- **bounce<=3**: any stage-gate failure must bounce back to the previous step for a fix, never ship with known failures; after 3 bounces on one step, stop immediately and escalate to a human decision
- **Failure fallback**: on sub-agent timeout/stall/verdict conflict, the leader may take over or spawn a new agent to redo it, without violating write/review separation

## 9. No Speculation Rules

- All actions must actually be executed; never give results based on guesswork without execution
- Cross-verify code/docs/external data sources; where they conflict, the actual code is authoritative
- Items that cannot be statically verified or where the environment is insufficient must be honestly marked "unverified/not executed"; never assert PASS by assumption

## 10. Information Search Rules

- All question/analysis/research tasks must use the **f-stack-info-search** skill to search for information
- Coverage: issue analysis, bug location, feature research, information gathering before design, technical Q&A, and any other scenario requiring research
- Follow the five parts of f-stack-info-search: architecture docs and knowledge graph -> commit history -> related issues/PRs -> public resources -> internal/external websites, blogs, WeChat articles, etc.
- Cross-validation: converge evidence from internal docs + external resources + actual code/testing; where they conflict, the actual code is authoritative
- Never answer or conclude based on guesswork without searching

## 11. Runtime Test Environment

- This machine has two NICs: the DPDK-exclusive NIC and eth1 are different cards
- Testing DPDK NIC programs: access the DPDK-managed NIC on this machine from the peer via `ssh f-stack-client` (use the `<DPDK_NIC_IP>` placeholder)
- Testing the kernel stack on this machine: use 127.0.0.1 on lo
- Stop processes via kill_process.sh, clean temp files via rm_tmp_file.sh, restore config.ini temp test values after testing, and never commit them

## 12. Task Sizing and Harness Workflow Rules

- Judge the task size automatically from the prompt or by the model: small tasks may be analyzed and executed directly; large tasks must follow these steps:
- 12.1 Feature research: first complete feature research using the multi-agent harness approach, producing a Chinese spec document (other spec-related skills may be installed and used) plus gate review; Chinese docs go under `docs/<FEATURE_NAME>_spec/zh_cn/`; **do not produce the English spec yet** (translate it only after feature acceptance); submit for human review
- 12.2 Implementation and acceptance: after the human review of the spec passes, a human prompt triggers the actual implementation and acceptance phase (multi-agent harness approach, following all multi-agent rules), completing code writing, CR, testing (unit tests and runtime tests), doc updates, and gate reviews at each milestone
- 12.3 Both spec generation and actual implementation must first produce a plan.md for human review before execution
- 12.4 Make multiple git commits by milestone
- 12.5 After test acceptance completes, translate the Chinese spec docs under `docs/<FEATURE_NAME>_spec/zh_cn/` into English (both file names and contents must be translated) and place them under `docs/<FEATURE_NAME>_spec/`

## 13. Test Gate Rules

- Any change involving code must complete unit tests and runtime regression tests
- Unit tests and runtime regression tests are subject to the same gate rules (bounce<=3, write/review separation, etc.; see section 8)