lean-spec / docs-site
AGENTS.md296 starsChanged 6 months agoMITView on GitHub
When working with the LeanSpec documentation site: Documentation folder structure must exactly match the sidebar hierarchy in sidebars.ts. Example: - Sidebar: Usage → CLI Usage → Creating & Managing Specs - File: ./docs/guide/usage/cli/creating-managing.mdx ✅ Every English .mdx file needs a Chinese translation in i18n/zh-Hans/docusaurus-plugin-content-docs/current/ with identical folder structure. CRITICAL: Translations must be professional, natural, and technically accurate. Avoid literal word-by-word translation. 1. Keep English Terms for Core Concepts Never translate these terms - they are technical concepts with established English…
1 other project uses a version of this.
Adopted by
Most recently taken up by
- codervisor/leanspecword for word, first seen May 20, 2026
Other versions1 project uses a version of this.
Word for word · 1
- codervisor/leanspec★ 294100% same
Edited · 0
None found.
Wrote their own version · 0
None found.
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
Where files are headingNew AGENTS.md files have more rules about keeping secrets out of the code, and fewer about code style.
Of the AGENTS.md files we read, the 33,315 first seen in the last six months, against the older ones: the kind of rule that gained most share, and the kind that lost most. About files like this in general, not this one, and an estimate, since a kind is a pattern in the words.
In this repository8 other files it gives its agents.
- AGENTS.mdAGENTS.md
- CLAUDE.mdCLAUDE.md
- leanspec-developmentSkill
- leanspec-dev-processSkill
- leanspec-pre-pushSkill
- leanspec-pr-lifecycleSkill
- watch-ciSkill
- leanspecSkill
The file
Show its rules and text
We split this AGENTS.md into the rules it gives an agent
22 rules. About 0 are common, 18 are distinctive, and 4 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈18
Distinctive · estimate
This author's own choices. Worth a look.
4
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 5
When working with the LeanSpec documentation site:
- Distinctive: line 7
File paths MUST align with sidebar structure: - No exceptions
- Very specific: line 10
Always validate builds: - Run npm run build before committing
- Very specific: line 24
Every English .mdx file needs a Chinese translation in i18n/zh-Hans/docusaurus-plugin-content-docs/current/ with identical folder structure.
- Distinctive: line 34
Never translate these terms - they are technical concepts with established English usage:
- Distinctive: line 56
When translating technical terms that don't have established Chinese equivalents, include the English term in parentheses on first use:
- Distinctive: line 68
After first use with English reference, you can use Chinese only in the same document.
- Distinctive: line 72
Avoid word-by-word literal translation.
- Distinctive: line 92
Keep code examples unchanged (English)
- Distinctive: line 93
Keep error messages unchanged (English)
- Distinctive: line 94
Keep file paths unchanged (English)
- Distinctive: line 101
Add spaces between Chinese and English: "使用 CLI 工具"
- Distinctive: line 102
Add spaces between Chinese and numbers: "版本 2.0"
- Distinctive: line 103
No spaces inside Chinese text: "这是示例" not "这 是 示 例"
- Distinctive: line 183
Before committing Chinese translations, verify:
- Distinctive: line 232
Must pass with no broken links, MDX errors, or missing translations.
- Distinctive: line 246
Run before committing Chinese content changes.
- Distinctive: line 251
Update Chinese translations (mirror structure exactly)
- Very specific: line 252
Update config files (sidebars.ts, docusaurus.config.ts)
- Very specific: line 253
Run npm run build - must succeed
- Distinctive: line 254
Verify pages in dev mode
- Distinctive: line 255
Commit only if build passes
≈ “Common” is an estimate: at least 1 in 5 of the 42,283 AGENTS.md files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
AI Agent Instructions for LeanSpec Documentation Site
Core Principles
When working with the LeanSpec documentation site:
- File paths MUST align with sidebar structure - No exceptions
- Chinese translations MUST mirror English docs - Complete parity required
- MDX formatting matters - Bold with quotes/Chinese needs special handling
- Always validate builds - Run
npm run buildbefore committing
Critical Rules
File Structure Alignment
Documentation folder structure must exactly match the sidebar hierarchy in sidebars.ts.
Example:
- Sidebar:
Usage → CLI Usage → Creating & Managing Specs - File:
./docs/guide/usage/cli/creating-managing.mdx✅
Translation Completeness
Every English .mdx file needs a Chinese translation in i18n/zh-Hans/docusaurus-plugin-content-docs/current/ with identical folder structure.
Chinese Translation Quality
CRITICAL: Translations must be professional, natural, and technically accurate. Avoid literal word-by-word translation.
Translation Principles
1. Keep English Terms for Core Concepts
Never translate these terms - they are technical concepts with established English usage:
- Core terms: Spec, LeanSpec, CLI, Token, README, frontmatter, MCP
- Commands:
lean-spec create,lean-spec update,lean-spec board, etc. - Status values:
draft,planned,in-progress,complete,archived - File types:
.md,.mdx,.json,.yaml - Technical terms: SDD (Spec-Driven Development), API, JWT, URL, JSON
Examples:
✅ "使用 `lean-spec create` 创建新 Spec"
❌ "使用 `精益规范创建` 创建新规格说明"
✅ "Spec 文件使用 Markdown 格式"
❌ "规格说明文件使用 Markdown 格式"
✅ "状态从 `planned` 变为 `in-progress`"
❌ "状态从"已计划"变为"进行中""2. Add English References for Technical Concepts
When translating technical terms that don't have established Chinese equivalents, include the English term in parentheses on first use:
✅ "上下文经济 (Context Economy)"
✅ "信噪比 (Signal-to-Noise Ratio)"
✅ "渐进式披露 (Progressive Disclosure)"
✅ "依赖图 (Dependency Graph)"
✅ "工作记忆 (Working Memory)"
❌ "上下文经济" (without English reference)After first use with English reference, you can use Chinese only in the same document.
3. Use Natural Chinese Expression
Avoid word-by-word literal translation. Use idiomatic Chinese that reads naturally:
❌ "为什么这个很重要" (literal: why this is important)
✅ "重要性" or "为什么重要" (natural)
❌ "规格文件" (literal: specification file)
✅ "Spec 文件" (natural, keeps technical term)
❌ "它是什么" (literal: what it is)
✅ "功能介绍" or "简介" (natural)
❌ "怎么做" (literal: how to do)
✅ "操作步骤" or "使用方法" (natural)4. Maintain Technical Accuracy
Balance readability with precision:
- Keep code examples unchanged (English)
- Keep error messages unchanged (English)
- Keep file paths unchanged (English)
- Translate explanatory text naturally
- Preserve technical meaning
5. Follow Chinese Typography Standards
- Use full-width punctuation: ,。!?()【】
- Add spaces between Chinese and English: "使用 CLI 工具"
- Add spaces between Chinese and numbers: "版本 2.0"
- No spaces inside Chinese text: "这是示例" not "这 是 示 例"
Translation Glossary
Always Keep in English:
| English | Chinese (Don't Use) | Usage |
| Spec | ❌ 规格/规范 | "创建新 Spec" ✅ |
| LeanSpec | ❌ 精益规范 | "LeanSpec 方法论" ✅ |
| CLI | ❌ 命令行界面 | "使用 CLI 命令" ✅ |
| Token | ❌ 令牌/标记 | "Token 数量" ✅ |
| README | ❌ 说明文件 | "README.md 文件" ✅ |
| frontmatter | ❌ 前置元数据 | "frontmatter 配置" ✅ |
| MCP | ❌ 模型上下文协议 | "MCP 服务器" ✅ |
Translate with English Reference (First Use):
| English | Chinese Translation | First Use Example |
| Context Economy | 上下文经济 | "上下文经济 (Context Economy) 原则" |
| Signal-to-Noise | 信噪比 | "信噪比 (Signal-to-Noise) 最大化" |
| Progressive Disclosure | 渐进式披露 | "渐进式披露 (Progressive Disclosure)" |
| Dependency Graph | 依赖图 | "查看依赖图 (Dependency Graph)" |
| Working Memory | 工作记忆 | "适应工作记忆 (Working Memory)" |
| Intent Over Implementation | 意图优于实现 | "意图优于实现 (Intent Over Implementation)" |
| Bridge the Gap | 弥合差距 | "弥合差距 (Bridge the Gap)" |
| Spec-Driven Development | 规格驱动开发 | "规格驱动开发 (Spec-Driven Development, SDD)" |
Pure Chinese Translation (Common Terms):
| English | Chinese | Notes |
| Overview | 概述 | Common, no English needed |
| Getting Started | 快速开始 | Standard phrase |
| Tutorial | 教程 | Common term |
| Examples | 示例 | Common term |
| Installation | 安装 | Common action |
| Configuration | 配置 | Common term |
| Usage | 使用 | Common term |
| Reference | 参考 | Common term |
| FAQ | 常见问题 | Common term |
| Best Practices | 最佳实践 | Common phrase |
Common Translation Patterns
Section Headers:
✅ "## 什么是 LeanSpec?"
✅ "## 快速开始"
✅ "## 核心概念"
✅ "## 为什么使用 LeanSpec"
❌ "## What is LeanSpec?" (in Chinese docs)
❌ "## Getting Started" (in Chinese docs)Feature Descriptions:
✅ "LeanSpec 是一种轻量级的规格驱动开发 (SDD) 方法论"
❌ "LeanSpec 是一个轻量级规范驱动的开发方法"
✅ "使用 `lean-spec board` 查看 Spec 看板"
❌ "使用 `lean-spec board` 查看规格说明看板"Technical Explanations:
✅ "Spec 文件使用 Markdown 格式,包含 frontmatter 元数据"
❌ "规格说明文件使用 Markdown 格式,包含前置元数据"
✅ "Token 数量影响上下文经济 (Context Economy)"
❌ "令牌数量影响上下文经济"Quality Checklist
Before committing Chinese translations, verify:
- All "Spec" references use "Spec" (not "规格" or "规范")
- All commands remain in English (e.g.,
lean-spec create) - Technical terms have English references on first use
- Chinese text reads naturally (not word-by-word translation)
- Full-width punctuation used consistently
- Spaces between Chinese and English/numbers
- Code blocks and examples unchanged
- No MDX syntax errors (run
pnpm validate:mdx)
See: specs/115-chinese-translation-quality/ for detailed guidelines and examples.
MDX Formatting
Chinese text with multiple bolds:
这与 **语法属性(Syntactic Properties)** 形成对比 ✅ (space before second **)Bold with quotes:
** "quoted text" ** ✅ (spaces inside bold markers)Mermaid Diagram Dark Theme Styling
CRITICAL: Mermaid diagrams MUST have custom styling for dark theme contrast. Default colors are unreadable in dark mode.
Always apply styles to Mermaid nodes:
```mermaid
graph LR
A[Node] --> B[Node]
style A fill:#e1f5ff,stroke:#1e3a8a,stroke-width:2px,color:#1e3a8a
style B fill:#fff4e1,stroke:#92400e,stroke-width:2px,color:#92400e
**Use color palette:** Light background + dark text for contrast in both themes. See `agents/documentation-quality-standards.md` section 6 for full color palette and examples.
### Build Validation
Before committing:
```bash
cd docs-site && npm run buildMust pass with no broken links, MDX errors, or missing translations.
MDX Syntax Validation
Validate source MDX files for syntax issues that cause build failures:
cd docs-site && pnpm validate:mdxThis checks Chinese docs and blogs for:
- Unescaped special characters (
<>{}) - Bold formatting spacing issues
- Other MDX syntax problems
Run before committing Chinese content changes.
Workflow
- Update English docs
- Update Chinese translations (mirror structure exactly)
- Update config files (
sidebars.ts,docusaurus.config.ts) - Run
npm run build- must succeed - Verify pages in dev mode
- Commit only if build passes
Detailed Guidelines
For comprehensive documentation quality standards, see agents/documentation-quality-standards.md.
Formula: Documentation Quality = Content × Structure × Translation Completeness
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

