agentleFS
codervisorcodervisor/leanspec/docs-site/AGENTS.md

leanspec / docs-site

AGENTS.md294 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

  • Other versions1 project uses a version of this.

    Word for word · 1

    1. codervisor/lean-spec★ 296100% 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.

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, 17 are distinctive, and 5 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈17

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 5

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    When working with the LeanSpec documentation site:

    line 5
  2. Distinctive:

    File paths MUST align with sidebar structure: - No exceptions

    line 7
  3. Very specific:

    Always validate builds: - Run npm run build before committing

    line 10
  4. Very specific:

    Every English .mdx file needs a Chinese translation in i18n/zh-Hans/docusaurus-plugin-content-docs/current/ with identical folder structure.

    line 24
  5. Distinctive:

    Never translate these terms - they are technical concepts with established English usage:

    line 34
  6. Distinctive:

    When translating technical terms that don't have established Chinese equivalents, include the English term in parentheses on first use:

    line 56
  7. Distinctive:

    After first use with English reference, you can use Chinese only in the same document.

    line 68
  8. Distinctive:

    Avoid word-by-word literal translation.

    line 72
  9. Distinctive:

    Keep code examples unchanged (English)

    line 92
  10. Distinctive:

    Keep error messages unchanged (English)

    line 93
  11. Distinctive:

    Keep file paths unchanged (English)

    line 94
  12. Distinctive:

    Add spaces between Chinese and English: "使用 CLI 工具"

    line 101
  13. Distinctive:

    Add spaces between Chinese and numbers: "版本 2.0"

    line 102
  14. Distinctive:

    No spaces inside Chinese text: "这是示例" not "这 是 示 例"

    line 103
  15. Distinctive:

    Before committing Chinese translations, verify:

    line 183
  16. Distinctive:

    Must pass with no broken links, MDX errors, or missing translations.

    line 232
  17. Distinctive:

    Run before committing Chinese content changes.

    line 246
  18. Distinctive:

    Update Chinese translations (mirror structure exactly)

    line 251
  19. Very specific:

    Update config files (sidebars.ts, docusaurus.config.ts)

    line 252
  20. Very specific:

    Run npm run build - must succeed

    line 253
  21. Distinctive:

    Verify pages in dev mode

    line 254
  22. Distinctive:

    Commit only if build passes

    line 255

≈ “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.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
AGENTS.md

AI Agent Instructions for LeanSpec Documentation Site

Core Principles

When working with the LeanSpec documentation site:

  1. File paths MUST align with sidebar structure - No exceptions
  2. Chinese translations MUST mirror English docs - Complete parity required
  3. MDX formatting matters - Bold with quotes/Chinese needs special handling
  4. Always validate builds - Run npm run build before 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:

EnglishChinese (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):

EnglishChinese TranslationFirst 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):

EnglishChineseNotes
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 build

Must 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:mdx

This checks Chinese docs and blogs for:

  • Unescaped special characters (< > { })
  • Bold formatting spacing issues
  • Other MDX syntax problems

Run before committing Chinese content changes.

Workflow

  1. Update English docs
  2. Update Chinese translations (mirror structure exactly)
  3. Update config files (sidebars.ts, docusaurus.config.ts)
  4. Run npm run build - must succeed
  5. Verify pages in dev mode
  6. 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

Download now (ZIP)

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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.